Add supporting documents

Last updated: March 25, 2026

Use the Platforms API to upload supporting documents for a sub-entity. These documents are used to verify their identity, business details, and financial information as part of the onboarding and verification process.

You can upload the following document types:

Identity verification documents
Company verification documents
Bank verification documents
Financial verification documents

To add supporting documentation to a sub-entity, follow these steps:

Generate a file upload link.
Upload the file.
Retrieve the file to verify status.
Attach the file to the sub-entity.

The Platforms API accepts the following types of documents for identity verification. Depending on the document type, you may need to provide both the front and back sides:

Document type	Sides required
Passport	Photo page only
Driving license	Front and back
National identity card	Front and back
Citizen card	Front and back
Residence permit	Front and back
Electoral ID	Front and back
Bank statement	Front only

Call the Upload a file endpoint and provide the sub-entity ID as the entity_id path parameter.

In the request body, provide the purpose field. This is the purpose of the document and can be one of:

additional_document
articles_of_association
bank_verification
certified_authorised_signatory
company_ownership
company_verification
financial_verification
identity_verification
proof_of_legality
proof_of_principal_address
shareholder_structure
tax_verification
proof_of_residential_address
proof_of_registration

For example, for an identity verification document, set purpose to identity_verification.

If the documentation requires both the back and front sides, you must create two different upload links.

post

https://files.checkout.com/files

Note

Notice that the sub-domain – files.checkout.com – is slightly different to Checkout.com's other endpoints.


1{
2  "purpose": "identity_verification"
3}

A successful response returns:

an upload URL for uploading the file.
an id that represents the file. You need this id to attach the file to the sub-entity.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}

Note

Only needed for sub-entities who have been onboarded as a company.


1{
2  "purpose": "company_verification"
3}

A successful response returns:

an upload URL for uploading the file.
an id that represents the file. You need this id to attach the file to the sub-entity.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}


1{
2  "purpose": "bank_verification"
3}

A successful response returns:

an upload URL for uploading the file.
an id that represents the file. You need this id to attach the file to the sub-entity.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}


1{
2  "purpose": "financial_verification"
3}

A successful response returns:

an upload URL for uploading the file.
an id that represents the file. You need this id to attach the file to the sub-entity.


1{
2  "id": "file_am2y22gp6wzwqgsyv5h2mldy3y",
3  "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"],
4  "maximum_size_in_bytes": "4194304",
5  "_links": {
6    "upload": {
7      "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
8    },
9    "self": {
10      "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y"
11    }
12  }
13}

Before uploading a file, make sure you meet the following requirements:

The uploaded file is no larger than 4MB.
For identity verification documents, the file is in either JPEG, JPG, or PNG format.
For bank statements, company verification, and financial verification documents, the file is in either JPEG, JPG, PNG, or PDF format.
If you are uploading a bank statement to verify a set of bank details, you configured your webhook server and subscribed to the payment_instrument_verification_passed and payment_instrument_verification_failed webhooks.

To upload a file, send a data-binary type request to the upload URL you received in the previous step, with the file attached.


1curl --location --request PUT "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
2--data-binary '@/C:/Users/Test/test.pdf'

A successful response returns a 200 HTTP response code, indicating the file has been uploaded.

You can retrieve information about a previously uploaded file and check its status.

A file can have one of the following statuses:

Verified – The file is ready to be used in an onboarding request.
Pending – The file is pending verification or virus scanning.
Invalid – See the status_reasons property for more information:
- invalid_mime_type– The mime type does not match the allowed content types for the specified document purpose – for example, a PDF document was uploaded for identity verification.
- file_size_limit_exceeded– The file is larger than 4MB.
Failed verification – The file is malicious.

To retrieve information about a previously uploaded file, call the Retrieve a file endpoint. Include the id of the file returned when you generated the file upload link in your request.

For example, https://files.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldy3y.

get

https://files.checkout.com/files/{file_id}


1{
2  "id": "file_bgwa24ijrknm6a3zlqydctnkou",
3  "mime_type": "image/jpeg",
4  "purpose": "identity_verification",
5  "size": 7111,
6  "status": "verified",
7  "uploaded_on": "2023-01-16T11:07:04.497Z",
8  "_links": {
9    "download": {
10      "href": "https://files.sandbox.checkout.com/files/ent_e5fxiiuec7yasswclx27zbpbcc/file_bbmcujt2fxmyh5pmeuz2bvvxd?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X"
11    },
12    "self": {
13      "href": "https://files.sandbox.checkout.com/files/file_bbmcujt2fxmyh5pmeuz2bvvxd"
14    }
15  }
16}


1{
2  "id": "file_a4q47zqvlgwdbladiuxrdjxxx",
3  "mime_type": "application/pdf",
4  "purpose": "identity_verification",
5  "size": 25692,
6  "status": "invalid",
7  "status_reasons": ["invalid_mime_type"],
8  "uploaded_on": "2023-01-16T11:01:32.226Z",
9  "_links": {
10    "self": {
11      "href": "https://files.sandbox.checkout.com/files/file_a4q47zqvlgwdbladiuxrdjxxx"
12    }
13  }
14}

You can attach a file to a sub-entity when you onboard a sub-entity, or update a sub-entity.

Within the relevant documents object in your request body, add an object that represents the purpose of the document. Depending on the type of document you are uploading, the object name must be one of:

additional_document
articles_of_association
bank_verification
certified_authorised_signatory
company_ownership
company_verification
financial_verification
identity_verification
proof_of_legality
proof_of_principal_address
shareholder_structure
tax_verification
proof_of_residential_address
proof_of_registration

Within this object, include the following fields:

type – The type of document used for the verification. See accepted document types.
front – The id returned when you uploaded the front side of the document.
back – The id returned when you uploaded the back side of the document. This is only required for document types that need both front and back images.


1{
2   "identity_verification":{
3      "type":"passport",
4      "front":"file_bgwa24ijrknm6a3zlqydctnkou"
5   }
6}


1{
2   "bank_verification":{
3      "type":"bank_statement",
4      "front":"file_bsdg24ijrknm6a3zlqydctnyai"
5   },
6   "articles_of_association":{
7      "type":"articles_of_association",
8      "front":"file_am2y22gp6wzwqgsyv5h2mldy3y"
9   },
10   "shareholder_structure":{
11      "type":"certified_shareholder_structure",
12      "front":"file_as2y22gp6wzwqgsyv5h2mlaz2d"
13   }
14}

Verification requirements

Learn about the information required for sub-entity verification.

Add supporting documents

Identity document types and requirements

Generate a file upload link

Note

Request examples

Response example

Note

Response example

Response example

Response example

Upload a file

Request example

Retrieve a file

Response examples

Attach a file to the sub-entity

Related topics

Verification requirements