> 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/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# Submitting documents

## Docs

- [Document types](https://docs.mangopay.com/guides/users/verification/documents/types.md): Learn about types of KYC/KYB document with Mangopay: which are required for natural and legal users, plus submission constraints and guidelines.
- [How to submit a KYC Document](https://docs.mangopay.com/guides/users/verification/documents/submission/how-to.md): Step-by-step guide to submitting verification (KYC/KYB) documents: uploading files, managing outcomes, and setting up webhooks.
- [Identity proof best practices](https://docs.mangopay.com/guides/users/verification/documents/submission/id-best-practices.md): See best practices for submitting identity proof documents and errors to avoid to ensure that the document can be read and validated.
- [Dealing with refusals](https://docs.mangopay.com/guides/users/verification/documents/submission/refusals.md): 


> **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page.

> 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/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# Document submission process

> **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.

## Process

The verification process can be broken down into the following steps:

The platform collects the necessary information for the user.

The platform collects the relevant document(s) from the user and submits them to Mangopay.

Against the information declared, Mangopay verifies the documents and either validates or refuses them.

In case of refusal, new documents may be required from the end user.

You can submit end users' verification documents with the dedicated KYC Documents endpoints.

Submission requires a minimum of 3 API calls:

* [Create the KYC Document](/api-reference/kyc-documents/create-kyc-document)
* Upload each file as a [KYC Document Page](/api-reference/kyc-documents/create-kyc-document-page) (this call must be repeated for each file)
* [Submit the KYC Document](/api-reference/kyc-documents/submit-kyc-document) by changing its status.

Follow the how-to guide for a step-by-step explanation:

#### [How to](/guides/users/verification/documents/submission/how-to)

Submit a KYC Document for verification

> **Note**
>
> **Note - Verification time**
>
> Verification takes on average 24 hours on
>
> working days
>
> to be completed by the Mangopay Compliance team.
>
> You can use [webhooks](/webhooks) to be notified of the KYC Document status update.

Mangopay returns the following statuses once the verification process is done:

* `VALIDATED` – The document is validated by Mangopay’s team.
* `REFUSED` – The document is rejected by Mangopay’s team.

The following status may also be returned as a result of the [Verification downgrade](/guides/users/verification/downgrade) mechanism.

* `OUT_OF_DATE` – The user's key details have been modified.
  The downgrade can be triggered after submission (in the case of identity proofs) and validation (in the case of all documents).

## File constraints

When uploading files as pages of the KYC Documents through the dedicated endpoints, you need to respect the the following constraints.

#### Format

Accepted formats: PDF, JPEG, JPG, PNG.

#### Encoding

All files must be Base64 encoded.

#### Size

File size (per KYC Document Page) is essential for good quality, therefore the following rules apply:

#### Identity proof

* Minimum size: 32KB
* Maximum size: about 7MB (10MB when Base64 encoded)

#### Other document types

* Minimum size: 1KB
* Maximum size: about 7MB (10MB when Base64 encoded)

#### Number of files per KYC Document

A maximum of 5 files can be submitted for a document, created as KYC Document Pages in the API.

This limit applies to all types of verification documents.

Note: A document typically requires 1 to 3 files, for example the front and back of an ID card, or a document and its translation.

## Best practices

Good quality submissions are necessary to effectively assess whether documents are genuine or not.

For identity proof documents, refer to:

#### [Guide](/guides/users/verification/documents/submission/id-best-practices)

Best practices for submitting ID documents

For other types, the document should be:

Compliant with the accepted documents for the legal entity’s country of registration.

Consistent with the information declared for the user, the legal representative, and any beneficial owners (if applicable).

Full and complete, meaning not censored, concealed, obscured, modified or otherwise altered in any way.

Accompanied by an official translation if **not** in one of the accepted languages. See the [Translations](/guides/users/verification/requirements/kyb-local#translations) section for more details.