# Add supporting documents Supporting documents Checkout.com may request for additional verification can be uploaded using the [Platforms API](https://api-reference.checkout.com/#tag/Platforms). 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: 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. --- ## 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/entities/{entityId}/files` **Sandbox** `POST` `https://files.sandbox.checkout.com/entities/{entityId}/files` ### 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, on behalf of 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 that have been onboarded as a company. ```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, on behalf of 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, on behalf of 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, on behalf of 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 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](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 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. ### 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 that the upload succeeded. --- ## 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 the request. For example, `https://files.checkout.com/entities/{entityId}/files/file_am2y22gp6wzwqgsyv5h2mldy3y`. **Production** `GET` `https://files.checkout.com/entities/{entityId}/files/{fileId}` **Sandbox** `GET` `https://files.sandbox.checkout.com/entities/{entityId}/files/{fileId}` ### 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": ["InvalidMimeType"], "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 Attach a file to a sub-entity when Checkout.com [onboards a sub-entity](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/submit-application.md), or [updates a sub-entity](https://www.checkout.com/docs/platforms/for-saas/manage-sub-entities/update-a-sub-entity.md). 1. 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` 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 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. **Sole trader** ```json { "individual":{ "first_name":"Toby", "last_name":"Arden", "place_of_birth":{ "country":"US" }, "address":{ "address_line1":"123 Anywhere St.", "city":"Anytown", "state":"AL", "zip":"123456", "country":"US" }, "date_of_birth":{ "day":11, "month":6, "year":1995 }, "email_address":"toby.arden@example.com" }, "roles":[ "ubo" ], "ownership_percentage":70, "documents":{ "identity_verification":{ "type":"passport", "front":"file_am2y22gp6wzwqgsyv5h2mldy3y" } } } ``` **Company** ```json { "tax_verification":{ "type":"ein_letter", "front":"file_a1pq22gp6wzwqgsyv5h2mldy11" }, "company_verification":{ "type":"incorporation_document", "front":"file_awhg22gp6wzwqgsyv5h2mldytf" }, "articles_of_association":{ "type":"articles_of_association", "front":"file_aad422gp6wzwqgsyv5h2mldy3y" }, "shareholder_structure":{ "type":"certified_shareholder_structure", "front":"file_ad5u22gp6wzwqgsyv5h2mldt5j" }, "proof_of_principal_address":{ "type":"proof_of_address", "front":"file_ae6v22gp6wzwqgsyv5h2mldu6k" } } ``` --- ## Identity document types and requirements 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 | --- ## Tax verification document types 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. | --- ## Related topics **[Verification requirements](https://www.checkout.com/docs/platforms/for-saas/onboard-sub-entities/collect-verification-information.md)** Learn about the information required for sub-entity verification.