> ## Documentation Index > Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit KYC data > Submit outstanding KYC requirements for a customer ## OpenAPI ````yaml PATCH /platform/v1/customers/{id}/kyc openapi: 3.1.0 info: title: MoonPay version: 1.0.0 servers: - url: https://api.moonpay.com description: Production Environment variables: {} - url: https://api.moonpay.dev description: Sandbox Environment variables: {} security: [] tags: - name: Assets - name: Quote - name: Customer - name: Identity - name: Transactions paths: /platform/v1/customers/{id}/kyc: patch: tags: - Customer summary: Submit KYC data for a customer description: >- Submits one or more outstanding KYC requirements for the customer and returns the updated customer. operationId: CustomersController.submitKyc parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateIdentityRequestBody' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Customer' required: - data unevaluatedProperties: not: {} '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: $ref: '#/components/schemas/DevPlatformApiErrorResponse' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Access is forbidden. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/DevPlatformApiErrorResponse' '409': description: The request conflicts with the current state of the server. content: application/json: schema: $ref: '#/components/schemas/ConflictError' security: - AccessTokenAuth: [] - SecretApiKeyInHeaderAuth: [] components: schemas: UpdateIdentityRequestBody: type: object properties: residentialAddress: allOf: - $ref: '#/components/schemas/IdentityResidentialAddressSubmission' description: The customer's residential address. basicDetails: allOf: - $ref: '#/components/schemas/IdentityBasicDetailsSubmission' description: The customer's basic personal details. phoneNumber: allOf: - $ref: '#/components/schemas/IdentityPhoneNumberSubmission' description: The customer's phone number in E.164 format. taxIdentifiers: type: array items: $ref: '#/components/schemas/IdentityTaxIdentifierSubmission' minItems: 1 description: >- Tax identifiers the customer is providing. At most one `ssn` and one `cpf` may be submitted; multiple `tin` entries are allowed only if their `country` values differ. questionnaires: type: array items: $ref: '#/components/schemas/IdentityQuestionnaireSubmission' minItems: 1 description: >- Due-diligence questionnaires the customer is submitting. Submit one entry per questionnaire listed under the `questionnaires` requirement on the identity; each questionnaire type may appear at most once. unevaluatedProperties: not: {} description: >- Request body for updating an identity by submitting one or more requirements. Submit only the fields whose requirements are still outstanding; at least one outstanding requirement must be provided. Customer: type: object required: - id - externalCustomerId - kyc properties: id: type: string format: uuid description: The customer's unique MoonPay identifier. externalCustomerId: anyOf: - type: string - type: 'null' description: >- The partner-provided identifier for this customer, if one was supplied. Null when the customer connected without an external identifier. kyc: allOf: - $ref: '#/components/schemas/CustomerKyc' description: KYC details for the customer. unevaluatedProperties: not: {} description: A MoonPay customer as seen by a partner. DevPlatformApiErrorResponse: type: object required: - code - message properties: code: allOf: - $ref: '#/components/schemas/DevPlatformApiErrorCodes' description: Code identifying the error type. examples: - forbidden - unauthorized - invalid_request message: type: string description: Human-readable error message. examples: - Forbidden - Not authorized - One or more request parameters are invalid. errors: type: array items: $ref: '#/components/schemas/DevPlatformErrorDetail' description: Optional list of field-level error details. examples: - - field: source.amount message: >- Source amount must be a numeric string. Example "100" or "10.25". unevaluatedProperties: not: {} description: Response body returned when a request fails. UnauthorizedError: type: object required: - code - message properties: code: type: string enum: - unauthorized message: type: string enum: - Not authorized unevaluatedProperties: not: {} description: Missing or invalid credentials. ForbiddenError: type: object required: - code - message properties: code: type: string enum: - forbidden message: type: string enum: - Forbidden unevaluatedProperties: not: {} description: Insufficient permissions. ConflictError: type: object required: - code - message properties: code: type: string enum: - conflict message: type: string enum: - Conflict unevaluatedProperties: not: {} description: The request conflicts with the current customer state. IdentityResidentialAddressSubmission: type: object properties: country: type: string pattern: ^[A-Z]{3}$ description: ISO 3166-1 alpha-3 country code. examples: - USA administrativeArea: type: string description: >- State, province, or territory. Required for country values that have subdivisions recognised by the platform (currently USA and CAN). examples: - CA locality: type: string minLength: 3 pattern: ^[^0-9<>&"/]+$ description: City, town, or locality of the residential address. examples: - San Francisco street: type: string minLength: 3 pattern: ^[^<>&"]+$ description: First line of the residential address (street). examples: - 1 Market Street subStreet: type: string minLength: 3 pattern: ^[^<>&"]+$ description: >- Optional second line of the residential address (apartment, unit, building). examples: - Apt 4B postalCode: type: string minLength: 3 pattern: ^[^<>&"]+$ description: Postal or ZIP code of the residential address. examples: - '94105' unevaluatedProperties: not: {} description: >- The customer's residential address. Submit only the fields listed as outstanding under the residentialAddress requirement on the identity. IdentityBasicDetailsSubmission: type: object properties: firstName: type: string minLength: 1 pattern: ^[^0-9<>&"/]+$ description: Customer's first/given name. examples: - Jane lastName: type: string minLength: 1 pattern: ^[^0-9<>&"/]+$ description: Customer's last/family name. examples: - Doe nationality: type: string pattern: ^[A-Z]{3}$ description: Customer's nationality (ISO 3166-1 alpha-3 country code). examples: - CAN dateOfBirth: type: string format: date description: Customer's date of birth (YYYY-MM-DD). examples: - '1990-05-15' unevaluatedProperties: not: {} description: >- The customer's basic personal details (name, nationality, date of birth). IdentityPhoneNumberSubmission: type: object required: - number properties: number: type: string description: The customer's phone number in E.164 format. examples: - '+14155551234' unevaluatedProperties: not: {} description: >- The customer's phone number submission. Submit only when the phoneNumber requirement is outstanding. IdentityTaxIdentifierSubmission: anyOf: - $ref: '#/components/schemas/IdentityTaxIdentifierGenericSubmission' - $ref: '#/components/schemas/IdentityTaxIdentifierSchemeSubmission' description: A tax identifier the customer is submitting. IdentityQuestionnaireSubmission: anyOf: - $ref: '#/components/schemas/IdentityCustomerDueDiligenceSubmission' - $ref: '#/components/schemas/IdentityEnhancedDueDiligenceSubmission' description: A due-diligence questionnaire the customer is submitting. CustomerKyc: type: object required: - status - requirements properties: status: allOf: - $ref: '#/components/schemas/CustomerKycStatus' description: The customer's KYC standing. requirements: allOf: - $ref: '#/components/schemas/Requirements' description: Outstanding and completed KYC requirements for the customer. challenge: allOf: - $ref: '#/components/schemas/IdentityVerificationChallenge' description: Hosted challenge the partner must surface to the customer. unevaluatedProperties: not: {} description: KYC details for a customer. DevPlatformApiErrorCodes: type: string enum: - unknown_error - unauthorized - forbidden - not_found - invalid_request - not_implemented - too_many_requests - not_allowed - conflict - unprocessable_entity - sse_timeout - sse_error - service_unavailable - requirements_incomplete - requirement_not_pending - verification_rejected - country_mismatch - upload_expired - unsupported_country - verification_pending - kyc_not_approved - no_outstanding_requirements - terms_accepted_at_out_of_range DevPlatformErrorDetail: type: object required: - message properties: field: type: string description: Field that caused the error. message: type: string description: Human-readable error message for this field. details: type: object unevaluatedProperties: {} description: >- Extra data that describes the error in more detail, useful when debugging or logging. Keys vary by error and are not part of the API contract. For example, an amount-limit error includes the limit value as "maxBuyAmount" or "minBuyAmount". unevaluatedProperties: not: {} IdentityTaxIdentifierGenericSubmission: type: object required: - type - country - value properties: type: type: string enum: - tin description: Identifies this entry as a TIN submission. country: type: string description: Country issuing the TIN, as an ISO 3166-1 alpha-3 country code. examples: - PRT value: type: string description: The TIN value as issued by the country's tax authority. examples: - '987654321' unevaluatedProperties: not: {} description: >- Submission for a Tax Identification Number. Partners supply the issuing country in the `country` field. IdentityTaxIdentifierSchemeSubmission: type: object required: - type - value properties: type: anyOf: - type: string enum: - ssn - type: string enum: - cpf description: Identifies which country-specific scheme this submission targets. value: type: string description: The identifier value, formatted as expected by the issuing scheme. examples: - '123456789' unevaluatedProperties: not: {} description: >- Submission for a country-specific tax identifier (SSN or CPF). The country is fixed by `type`; no `country` value is required. IdentityCustomerDueDiligenceSubmission: type: object required: - type - answers properties: type: type: string enum: - customerDueDiligence description: Identifies which questionnaire these answers are for. answers: allOf: - $ref: '#/components/schemas/CustomerDueDiligenceAnswers' description: The questionnaire answers. unevaluatedProperties: not: {} description: A Customer Due Diligence questionnaire submission. IdentityEnhancedDueDiligenceSubmission: type: object required: - type - answers properties: type: type: string enum: - enhancedDueDiligence description: Identifies which questionnaire these answers are for. answers: allOf: - $ref: '#/components/schemas/EnhancedDueDiligenceAnswers' description: The questionnaire answers. unevaluatedProperties: not: {} description: An Enhanced Due Diligence questionnaire submission. CustomerKycStatus: type: string enum: - collecting - verifying - active - unavailable - not_created description: >- The customer's KYC standing with you. `not_created` means no KYC session exists yet for this customer. Requirements: type: object properties: basicDetails: allOf: - $ref: '#/components/schemas/RequirementEntry' description: >- The customer's basic personal details (first name, last name, date of birth, nationality). examples: - status: incomplete requiredFields: - firstName - lastName - dateOfBirth - nationality residentialAddress: allOf: - $ref: '#/components/schemas/RequirementEntry' description: The customer's residential address. examples: - status: incomplete requiredFields: - street - locality - postalCode - administrativeArea identityDocuments: allOf: - $ref: '#/components/schemas/RequirementEntry' description: >- Identity document submission (passport, driver's license, residence permit, etc.). examples: - status: incomplete selfie: allOf: - $ref: '#/components/schemas/RequirementEntry' description: Selfie photo submission. examples: - status: incomplete taxIdentifiers: allOf: - $ref: '#/components/schemas/RequirementEntry' description: Tax identifier submission (SSN, CPF, TIN, etc.). examples: - status: incomplete requiredFields: - ssn proofOfAddress: allOf: - $ref: '#/components/schemas/RequirementEntry' description: Proof-of-address document submission. examples: - status: incomplete phoneNumber: allOf: - $ref: '#/components/schemas/RequirementEntry' description: Customer's phone number in E.164 format. examples: - status: incomplete questionnaires: allOf: - $ref: '#/components/schemas/RequirementEntry' description: >- Due-diligence questionnaires the customer must complete (Customer Due Diligence and Enhanced Due Diligence). When incomplete, `requiredFields` lists the outstanding questionnaire types. examples: - status: incomplete requiredFields: - customerDueDiligence - enhancedDueDiligence unevaluatedProperties: not: {} description: >- Outstanding and completed requirements for the identity, keyed by requirement category. Only requirements that apply to the customer are present. IdentityVerificationChallenge: type: object required: - url - expiresAt properties: url: type: string description: >- Fully-formed challenge URL. Render directly without parsing; the URL embeds the challenge token. expiresAt: type: string format: date-time description: >- Timestamp at which the challenge URL expires. Partners must surface the challenge to the customer before this time. unevaluatedProperties: not: {} description: >- A MoonPay-hosted challenge a partner must surface to the customer to complete identity verification. CustomerDueDiligenceAnswers: type: object required: - employmentStatus - accountPurpose - grossAnnualIncome - sourceOfWealth - transactionFrequencyPerMonth - expectedTransactionAmountPerMonth properties: employmentStatus: allOf: - $ref: '#/components/schemas/CddEmploymentStatus' description: The customer's employment status. accountPurpose: allOf: - $ref: '#/components/schemas/CddAccountPurpose' description: The customer's primary purpose for the account. grossAnnualIncome: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: >- The customer's gross annual income. Denominate the amount in the reporting currency for the customer's `residentialAddress.country`. See `MonetaryAmount` for the country-to-currency mapping. If the customer's local currency differs, convert the amount to the reporting currency before submitting, using a current exchange rate. sourceOfWealth: allOf: - $ref: '#/components/schemas/CddSourceOfWealth' description: The customer's primary source of wealth. transactionFrequencyPerMonth: type: integer format: int32 description: >- Expected number of transactions per month, a strictly positive integer. exclusiveMinimum: 0 examples: - 7 expectedTransactionAmountPerMonth: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: >- Expected total transaction amount per month. Denominate the amount in the reporting currency for the customer's `residentialAddress.country`. See `MonetaryAmount` for the country-to-currency mapping. unevaluatedProperties: not: {} description: Answers for the Customer Due Diligence questionnaire. EnhancedDueDiligenceAnswers: type: object required: - profession - netWorth properties: profession: allOf: - $ref: '#/components/schemas/EddProfession' description: The customer's profession. netWorth: allOf: - $ref: '#/components/schemas/MonetaryAmount' description: >- The customer's net worth. Denominate the amount in the reporting currency for the customer's `residentialAddress.country`. See `MonetaryAmount` for the country-to-currency mapping. unevaluatedProperties: not: {} description: Answers for the Enhanced Due Diligence questionnaire. RequirementEntry: type: object required: - status properties: status: allOf: - $ref: '#/components/schemas/RequirementItemStatus' description: Whether the requirement has been completed. requiredFields: type: array items: $ref: '#/components/schemas/RequirementFieldName' description: >- When status is incomplete, the outstanding fields the customer must provide for this requirement. Populated for `basicDetails`, `residentialAddress`, `taxIdentifiers`, and `questionnaires`; omitted when status is complete or for other requirement types, which do not surface field-level detail. unevaluatedProperties: not: {} description: Status of a single requirement group on an identity. CddEmploymentStatus: type: string enum: - employedOrSelfEmployed - retired - student - unemployed description: The customer's employment status. CddAccountPurpose: type: string enum: - investing - payments - purchasingDigitalAssets - purchasingGoodsOrServices - trading description: The customer's primary purpose for the account. MonetaryAmount: type: object required: - currency - amount properties: currency: allOf: - $ref: '#/components/schemas/SupportedCurrency' description: >- The fiat currency code, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. Must be the reporting currency for the customer's `residentialAddress.country`. See the country-to-currency table above. amount: allOf: - $ref: '#/components/schemas/MonetaryDecimal' description: >- The amount as a decimal string, strictly greater than zero. Must not have more than 2 decimal places. examples: - '1234.56' - '55000' unevaluatedProperties: not: {} description: >- A monetary amount. The `currency` must be the reporting currency for the customer's `residentialAddress.country`: | Residential address country | Reporting currency | | --------------------------- | ------------------ | | GBR | GBP | | AUS, NZL | AUD | | EEA (European Economic Area) countries | EUR | | All other countries, including USA and CAN | USD | The expected value is fixed by the residential address country, but `currency` is still required: it acts as an explicit confirmation so amounts are never silently misinterpreted. Submitting any other currency is rejected with a 400 validation error that identifies the expected currency, for example `Expected currency EUR for residentialAddress.country CZE, got PLN`. If the customer's local currency differs from the reporting currency, for example CZK or PLN in an EEA country, convert the amount to the reporting currency before submitting, using a current exchange rate. CddSourceOfWealth: type: string enum: - salary - savings - investments - cryptoTrading - other description: The customer's primary source of wealth. EddProfession: type: string enum: - agriculture - artsAndEntertainment - businessOwner - education - financialServices - healthcare - industrialTradesAndTransport - informationAndTechnology - legalAndProfessionalServices - publicSector - realEstate - retail - seniorManagement description: The customer's profession. RequirementItemStatus: type: string enum: - incomplete - complete description: The completion state of a requirement item. RequirementFieldName: type: string enum: - firstName - lastName - dateOfBirth - nationality - street - locality - postalCode - country - administrativeArea - ssn - cpf - tin - customerDueDiligence - enhancedDueDiligence description: >- A field a customer must provide to fulfil a requirement. Members match the field names used in the requirement-fulfilment endpoints (e.g. PATCH /platform/v1/identities/{id}). SupportedCurrency: type: string enum: - AUD - USD - EUR - GBP description: >- The fiat currency codes supported for monetary amounts, as [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) codes. MonetaryDecimal: type: string pattern: ^[0-9]+(\.[0-9]{1,2})?$ description: >- A monetary amount expressed as a decimal string, e.g. "55000" or "1234.56". securitySchemes: AccessTokenAuth: type: http scheme: bearer description: |- Bearer authentication header using an access token. Example: `Authorization: Bearer ` SecretApiKeyInHeaderAuth: type: apiKey in: header name: X-Api-Key description: |- Secret key authentication via the `X-Api-Key` header. Example: `X-Api-Key: ` ````