> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/guides/users/verification/documents/submission/how-to/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# How to submit a KYC Document

> **Warning**
>
> **Caution – Legacy solution**
>
> This page relates to the legacy solution for submitting KYC/KYB documents via the API KYC Document endpoints. New integrations must use the [hosted KYC/KYB solution](/guides/users/verification/hosted) relying on the [IDV Session](/api-reference/idv-sessions/create-idv-session) endpoints.
>
> Platforms with existing integrations should refer to email communications for details about the transition timeline.

## Introduction

This how-to guide will show you how to successfully submit a KYC Document for validation by Mangopay.

> **Info**
>
> **Prerequisites**
>
> * A `ClientId` and an API key – if you don't have these, [contact Sales](https://mangopay.com/contact) to get access to the [Mangopay Dashboard](https://hub.mangopay.com/)
> * An Owner user (natural or legal)

The KYC Document object allows you to submit any type of verification document for your users. Find out more about the different types in the [Types of verification document](/guides/users/verification/documents/types) article.

> **Note**
>
> **Note - Follow best practices for identity documents**
>
> In Production, `IDENTITY_PROOF` documents must adhere to best practices to avoid refusal. Communicate our [guidelines for IDs](/guides/users/verification/documents/submission/id-best-practices) to your end users to help them upload good-quality documents and optimize your acceptance rate.

## Test data

You can simulate the acceptance or refusal of a KYC Document in Sandbox. To do so, when you create the KYC Document (Step 1 below), set the `Tag` to the relevant (case-sensitive) value to produce the desired outcome after submission (Step 4):

<table>
  <thead>
    <tr>
      <th class="header">
        `Tag` value
      </th>

      <th class="header">
        Final `Status`
      </th>

      <th class="header">
        Final `RefusedReasonType`
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `accept`
      </td>

      <td class="table-content">
        `VALIDATED`
      </td>

      <td class="table-content">
        `null`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_unreadable`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `UNREADABLE`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_not_accepted`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `DOCUMENT_NOT_ACCEPTED`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_expired`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `DOCUMENT_HAS_EXPIRED`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_incomplete`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `DOCUMENT_INCOMPLETE`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_missing`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `DOCUMENT_MISSING`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_no_user_data_match`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `DOCUMENT_DO_NOT_MATCH_USER_DATA`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_falsified`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `DOCUMENT_FALSIFIED`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_underage`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `UNDERAGE_PERSON`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `refuse_specific_case`
      </td>

      <td class="table-content">
        `REFUSED`
      </td>

      <td class="table-content">
        `SPECIFIC_CASE`
      </td>
    </tr>
  </tbody>
</table>

## 1. Create the KYC Document

Create the document with the `UserId`, indicating which type is being submitted. In Sandbox, set the `Tag` to the desired test outcome, for example, `accept`.

> [**POST** /v2.01/\{ClientId}/users/\{UserId}/kyc/documents](/api-reference/kyc-documents/create-kyc-document)

The response shows the `Status` as `CREATED` and contains an `Id`, which is the unique identifier of the KYC Document object. You need to save this for the next step.

## 2. Upload a file to the KYC Document

Now that you have created the KYC Document container, you can upload files to it to be submitted.

With the `Id` of the KYC Document as the `KycDocumentId` path parameter, create the KYC Document Page containing the file uploaded by the user. The file must be encoded in Base64 (which is handled natively in our SDKs) and respect the format and size constraints described in the [submission](/guides/users/verification/documents/submission#file-constraints) article.

> [**POST** /v2.01/\{ClientId}/users/\{UserId}/kyc/documents/\{KycDocumentId}/pages](/api-reference/kyc-documents/create-kyc-document-page)

The 204 No content response means that the file has been uploaded successfully.

> **Warning**
>
> **Warning - Storage of KYC documents prohibited**
>
> You’re not allowed to store verification documents (in any format, even encoded) on your side unless you have permission from the appropriate authorities in your country.

## 3. Upload additional files as needed

Repeat Step 2 as many times as necessary. Each file of the real-life document requires a separate API call (Step 2) to upload the file in a dedicated KYC Document Page.

You can upload up to 5 files to each KYC Document, and each upload requires a call to the **POST Create a KYC Document Page** endpoint. Each file can contain as many real-life pages as required.

For example:

* National identity cards typically have 2 files: the front side and back side of the card.
* Passports have 1 file: the full-page spread displaying the photo.
* Documents for legal users may have many physical pages but in one file, so requiring one API call to create the KYC Document Page. If a [translation is required](/guides/users/verification/requirements/kyb-local#translations), this should be uploaded as a second file of the same KYC Document.

## 4. Submit the KYC Document

Once all files are uploaded, submit the document for review by Mangopay's teams by changing the `Status` from `CREATED` to `VALIDATION_ASKED`.

> [**PUT**/v2.01/\{ClientId}/users/\{UserId}/kyc/documents/\{KycDocumentId}](/api-reference/kyc-documents/submit-kyc-document)

## 5. Set up relevant webhooks (recommended)

There are dedicated [event types](/webhooks/event-types) to provide [webhook notifications](/webhooks) of the outcome of the review by Mangopay:

* `KYC_SUCCEEDED`, notifying that the KYC Document status has changed to `VALIDATED`.
* `KYC_FAILED`, notifying that the KYC Document status has changed to `REFUSED`.

For the `IDENTITY_PROOF` and `REGISTRATION_PROOF` documents, the document can be downgraded as a result of modifying user information. This is notified with the hook:

* `KYC_OUTDATED`, notifying that the status has changed to `OUT_OF_DATE`.

> **Note**
>
> **Note - Refused or downgraded documents must be re-created**
>
> A KYC Document with the status `REFUSED` or `OUT_OF_DATE` can’t be re-submitted. You need to create a new document and submit it again.
>
> In the case of a [refusal](/guides/users/verification/documents/submission/refusals), information about why it was refused is available in the `RefusedReasonType` and `RefusedReasonMessage` parameters.

If all the required documents are validated, then the user obtains the verified status. You can be notified of this event with the hook:

* `USER_KYC_REGULAR`, notifying that the `KYCLevel` parameter of the user object has changed to `REGULAR`

For more information on the requirements for user verification, see:

#### [Guide](/guides/users/verification/requirements)

Requirements by user type

## Related resources

#### [Guide](/guides/users/verification/requirements)

Learn about verification requirements for each user type