---
title: "Create a KYC Document"
method: POST
path: "/v2.01/{ClientId}/users/{UserId}/kyc/documents"
tags: ["kycDocuments"]
---

# Create a KYC Document

`POST /v2.01/{ClientId}/users/{UserId}/kyc/documents`

Create a container for files to be submitted

<Warning icon="fa-regular fa-triangle-exclamation">
**Caution – Legacy endpoints being superseded by the hosted KYC/KYB solution**

Mangopay's [hosted KYC/KYB solution](/guides/users/verification/hosted) is becoming mandatory for all platforms (relying on the [IDV Session](/api-reference/idv-sessions/idv-session-object) object). The legacy KYC Document endpoints remain available for the sole purposes of [sending additional documents](/guides/users/verification/hosted#sending-additional-documents), but this use case will also be handled by the hosted solution in future.
</Warning>

In Sandbox, you can set the KYC Document `Tag` to `accept` to simulate acceptance of the document after submission. Other values are available to simulate different refusal reasons – [see the guide for details](/guides/users/verification/documents/submission/how-to).

## Path parameters

- `ClientId` string, required
- `UserId` string, required

## Headers

- `Authorization` string, required

## Request body

- CreateADisputeDocumentRequest
  - `Type` string, required — **Allowed values:** `DELIVERY_PROOF`, `INVOICE`, `REFUND_PROOF`, `USER_CORRESPONDANCE`, `USER_ACCEPTANCE_PROOF`, `PRODUCT_REPLACEMENT_PROOF`, `OTHER` The type of the dispute document.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.

## Response `200`

Success

- KYCDocumentResponse
  - `Type` string — **Returned values:** `IDENTITY_PROOF`, `REGISTRATION_PROOF`, `ARTICLES_OF_ASSOCIATION`, `SHAREHOLDER_DECLARATION`, `ADDRESS_PROOF` The type of the document for the user verification.
  - `UserId` string — The unique identifier of the user.
  - `Flags` string[] — **Returned values:** A code from the <a href="/guides/users/verification/documents/submission/refusals" target="_blank">Flags list</a>. The series of codes providing more precision regarding the reason why the identity proof document was refused. You can review the explanations for each code in the <a href="/guides/users/verification/documents/submission/refusals" target="_blank">Flags list</a>.
  - `Id` string — Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details) The unique identifier of the object.
  - `Tag` string — Max. length: 255 characters Custom data that you can add to this object.
  - `CreationDate` integer — Unix timestamp (UTC) of the date and time the object was created.
  - `ProcessedDate` integer — Unix timestamp (UTC) of the date and time the document was processed by Mangopay's team.
  - `Status` string — **Returned values:** `CREATED`, `VALIDATION_ASKED`, `VALIDATED`, `REFUSED`, `OUT_OF_DATE` The status of the document: - `CREATED` – The document container is created and files can be uploaded using the [POST Create a KYC Document Page](/api-reference/kyc-documents/create-kyc-document-page) endpoint before submission. - `VALIDATION_ASKED` – The document is submitted to Mangopay for validation. - `VALIDATED` – The document is validated by Mangopay's teams. - `REFUSED` – The document is rejected by Mangopay's teams and a new KYC Document object needs to be created to resubmit it. You can learn more about the reason why it was refused in the `RefusedReasonType` parameter. - `OUT_OF_DATE` – The document is downgraded and a new KYC Document object needs to be created to resubmit it.
  - `RefusedReasonType` string — **Returned values:** DOCUMENT_DO_NOT_MATCH_USER_DATA, DOCUMENT_FALSIFIED, DOCUMENT_HAS_EXPIRED, DOCUMENT_INCOMPLETE, DOCUMENT_MISSING, DOCUMENT_NOT_ACCEPTED, DOCUMENT_UNREADABLE, SPECIFIC_CASE, UNDERAGE_PERSON Returned `null` unless `Status` is `REFUSED`. The reason for the document refusal. See the <a href="/guides/users/verification/documents/submission/refusals">refused reason types</a> for more information depending on the document type.
  - `RefusedReasonMessage` string — Max. length: 255 characters **Default value:** null Additional information about why the KYC Document was refused, provided by Mangopay's team.

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.dev/mangopay/apis/api-reference.md) · [All operations](https://skmtc.dev/mangopay/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mangopay/api-reference/revisions/fafbd0c69654/schema)