Add supporting documents
Beta

Last updated: September 16, 2026

Supporting documents Checkout.com may request for additional verification can be uploaded using the Platforms API.

Sub-entities can upload the following document types:

Identity verification documents
Company verification documents
Bank verification documents
Address verification documents

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

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

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/entities/{entityId}/files


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, on behalf of 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 that 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, on behalf of 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, on behalf of 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, on behalf of 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 the following requirements are met:

The uploaded file is no larger than 4MB.
For identity verification documents, the file must be 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 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 on behalf of a sub-entity, 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 that the upload succeeded.

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 the request.

For example, https://files.checkout.com/entities/{entityId}/files/file_am2y22gp6wzwqgsyv5h2mldy3y.

get

https://files.checkout.com/entities/{entityId}/files/{fileId}


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": ["InvalidMimeType"],
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}

Attach a file to a sub-entity when Checkout.com onboards a sub-entity, or updates a sub-entity.

Within the relevant documents object in the request body, add an object that represents the document's purpose. Choose the object name based on the document type:

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 the front side of the document is uploaded.
back – The id returned when the back side of the document is uploaded. This is only required for document types that need both front and back images.


1{
2   "individual":{
3      "first_name":"Toby",
4      "last_name":"Arden",
5      "place_of_birth":{
6         "country":"US"
7      },
8      "address":{
9         "address_line1":"123 Anywhere St.",
10         "city":"Anytown",
11         "state":"AL",
12         "zip":"123456",
13         "country":"US"
14      },
15      "date_of_birth":{
16         "day":11,
17         "month":6,
18         "year":1995
19      },
20      "email_address":"toby.arden@example.com"
21   },
22   "roles":[
23      "ubo"
24   ],
25   "ownership_percentage":70,
26   "documents":{
27      "identity_verification":{
28         "type":"passport",
29         "front":"file_am2y22gp6wzwqgsyv5h2mldy3y"
30      }
31   }
32}


1{
2   "tax_verification":{
3      "type":"ein_letter",
4      "front":"file_a1pq22gp6wzwqgsyv5h2mldy11"
5   },
6   "company_verification":{
7      "type":"incorporation_document",
8      "front":"file_awhg22gp6wzwqgsyv5h2mldytf"
9   },
10   "articles_of_association":{
11      "type":"articles_of_association",
12      "front":"file_aad422gp6wzwqgsyv5h2mldy3y"
13   },
14   "shareholder_structure":{
15      "type":"certified_shareholder_structure",
16      "front":"file_ad5u22gp6wzwqgsyv5h2mldt5j"
17   },
18   "proof_of_principal_address":{
19      "type":"proof_of_address",
20      "front":"file_ae6v22gp6wzwqgsyv5h2mldu6k"
21   }
22}

The Platforms API accepts the following types of documents for identity verification. Depending on the document type, we need 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

For sub-entities in the United States, the tax_verification.type field accepts the following IRS-issued documents:

Document type	Description
`ein_letter`	IRS-issued EIN confirmation letter (CP 575 or 147C).
`irs_501c3_certification_letter`	IRS 501(c)(3) certification letter for tax-exempt non-profits.
`irs_determination_letter`	IRS determination letter confirming the entity's tax classification.
`gen_letter`	IRS Group Exemption Number (GEN) letter, for entities covered by a group ruling.

Verification requirements

Learn about the information required for sub-entity verification.

Add supporting documents
Beta

Generate a file upload link

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

Identity document types and requirements

Tax verification document types

Related topics

Verification requirements