# Add supporting documents Use the [Platforms API](https://api-reference.checkout.com/#tag/Platforms) 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: 1. Generate a file upload link. 2. Upload the file. 3. Retrieve the file to verify status. 4. Attach the file to the sub-entity. --- ## Identity document types and requirements 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 | --- ## Generate a file upload link Call the [Upload a file](https://api-reference.checkout.com/tag/Platforms/#operation/uploadAFile) 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. **Production** `POST` `https://files.checkout.com/files` **Sandbox** `POST` `https://files.sandbox.checkout.com/files` > **Note** > > Notice that the sub-domain – `files.checkout.com` – is slightly different to Checkout.com's other endpoints. ### Request examples **Identity documentation** ```json { "purpose": "identity_verification" } ``` ### Response example 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. ```json { "id": "file_am2y22gp6wzwqgsyv5h2mldy3y", "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg"], "maximum_size_in_bytes": "4194304", "_links": { "upload": { "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X" }, "self": { "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y" } } } ``` **Company documentation** > **Note** > > Only needed for sub-entities who have been [onboarded as a company](https://www.checkout.com/docs/platforms/onboarding.md#Sub-entity_types). ```json { "purpose": "company_verification" } ``` ### Response example 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. ```json { "id": "file_am2y22gp6wzwqgsyv5h2mldy3y", "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"], "maximum_size_in_bytes": "4194304", "_links": { "upload": { "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X" }, "self": { "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y" } } } ``` **Bank documentation** ```json { "purpose": "bank_verification" } ``` ### Response example 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. ```json { "id": "file_am2y22gp6wzwqgsyv5h2mldy3y", "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"], "maximum_size_in_bytes": "4194304", "_links": { "upload": { "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X" }, "self": { "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y" } } } ``` **Financial documentation** ```json { "purpose": "financial_verification" } ``` ### Response example 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. ```json { "id": "file_am2y22gp6wzwqgsyv5h2mldy3y", "document_types_for_purpose": ["image/png", "image/jpg", "image/jpeg", "application/pdf"], "maximum_size_in_bytes": "4194304", "_links": { "upload": { "href": "https://s3.eu-west-1.amazonaws.com/mp-files-api-staging-sbox/ent_e5fxiiuec7yasswclx27zbpbcc/file_am2y22gp6wzwqgsyv5h2mldbb6y?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X" }, "self": { "href": "https://files.sandbox.checkout.com/files/file_am2y22gp6wzwqgsyv5h2mldbb6y" } } } ``` --- ## Upload a file 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](https://www.checkout.com/docs/developer-resources/event-notifications/receive-webhooks/configure-your-webhook-server.md) 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. ### Request example ```bash curl --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" --data-binary '@/C:/Users/Test/test.pdf' ``` A successful response returns a `200` HTTP response code, indicating the file has been uploaded. --- ## Retrieve a file 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](https://api-reference.checkout.com/tag/Platforms/#operation/retrieveAFile) 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`. **Production** `GET` `https://files.checkout.com/files/{file_id}` **Sandbox** `GET` `https://files.sandbox.checkout.com/files/{file_id}` ### Response examples **200 – File verified** ```json { "id": "file_bgwa24ijrknm6a3zlqydctnkou", "mime_type": "image/jpeg", "purpose": "identity_verification", "size": 7111, "status": "verified", "uploaded_on": "2023-01-16T11:07:04.497Z", "_links": { "download": { "href": "https://files.sandbox.checkout.com/files/ent_e5fxiiuec7yasswclx27zbpbcc/file_bbmcujt2fxmyh5pmeuz2bvvxd?AWSAccessKeyId=XX&Expires=1673456742&Signature=fg9Eq3mQBXrlnbeWCTyrURlBxQ%3X" }, "self": { "href": "https://files.sandbox.checkout.com/files/file_bbmcujt2fxmyh5pmeuz2bvvxd" } } } ``` **200 – File invalid** ```json { "id": "file_a4q47zqvlgwdbladiuxrdjxxx", "mime_type": "application/pdf", "purpose": "identity_verification", "size": 25692, "status": "invalid", "status_reasons": ["invalid_mime_type"], "uploaded_on": "2023-01-16T11:01:32.226Z", "_links": { "self": { "href": "https://files.sandbox.checkout.com/files/file_a4q47zqvlgwdbladiuxrdjxxx" } } } ``` --- ## Attach a file to the sub-entity You can attach a file to a sub-entity when you [onboard a sub-entity](https://www.checkout.com/docs/platforms/onboard-sub-entities/submit-application/onboard-with-the-api.md), or [update a sub-entity](https://www.checkout.com/docs/platforms/manage-sub-entities/update-a-sub-entity.md). 1. 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` 2. Within this object, include the following fields: - `type` – The type of document used for the verification. See [accepted document types](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/add-supporting-documents.md#Identity_document_types_and_requirements). - `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. **Sole trader** ```json { "identity_verification":{ "type":"passport", "front":"file_bgwa24ijrknm6a3zlqydctnkou" } } ``` **Company** ```json { "bank_verification":{ "type":"bank_statement", "front":"file_bsdg24ijrknm6a3zlqydctnyai" }, "articles_of_association":{ "type":"articles_of_association", "front":"file_am2y22gp6wzwqgsyv5h2mldy3y" }, "shareholder_structure":{ "type":"certified_shareholder_structure", "front":"file_as2y22gp6wzwqgsyv5h2mlaz2d" } } ``` --- ## Related topics **[Verification requirements](https://www.checkout.com/docs/platforms/onboard-sub-entities/collect-verification-information.md)** Learn about the information required for sub-entity verification.