Table of contents

• Overview
  • Upload document data only
  • Response explained
  • Supported document types
• Specifics of adding company documents
  • Request attributes and element fields
  • Supported company document types
  • Response

Overview

Use this method to:

• Add documents to verification flows for individual applicants.
• Add company documents to company applicant profiles.

The method gets a multipart form:

• Document JSON metadata.
• [Optionally] A document photo or scanned copy.

If the document with the same idDocType and country already exists, the new data will be merged with the existing one, and any existing data will be overwritten if it is present in the new object. However, a new image will always be added.

If you do not yet know the document metadata, include the mandatory idDocType and country fields. For example, you can send PASSPORT and GBR.

To add a proof of address or identity type of documents, it is advised to use the X-Return-Doc-Warnings header with the value of true, which allows determining if the document data is readable and acceptable before moving the applicant to the pending status. In response, the errors or warnings array will be present.

If you encounter errors during the upload process, the image you uploaded will be marked as inactive. This means that it will not be used as the primary document for the verification step. You will need to upload another image in order to proceed with the verification process successfully. For double-sided documents (FRONT_SIDE and BACK_SIDE of the idDocType value), both images will be marked as inactive, even if you have got an error for only one of them. An array of warnings just makes a notice that there might be something wrong with the document.

📘

Note

• If a document is double-sided, submit two images and set up the idDocSubType properly (FRONT_SIDE and BACK_SIDE). Make sure to send BACK_SIDE if FRONT_SIDE was already sent, otherwise verification step will not be completed, and you will not be able to initiate a check.
• Warnings and errors are shown only for the first four attempts to upload the document. For the next cases, we assume that the document should be checked within the full verification process.
• We may change the country and idDocType values that were sent to us on image upload; if such a mapping is important on your side, make sure to compare these two objects from our response.

🚧

Attention

The applicant cannot be moved to the pending status for a check if one of the verification steps is not active (does not have active images). To check if a verification step is active, use this method.

Upload document data only

If you need to upload only the document data, use the following request:

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5b75a5e80a975a3ef2102a87/info/idDoc' \
  -H 'Content-Type: multipart/form-data' \
  -F 'metadata={
  	"idDocType": "PASSPORT",
  	"country": "GBR",
  	"number": "123456789",
  	"issuedDate": "2015-01-02",
  	"dob": "2000-02-01",
  	"placeOfBirth": "London"
	}'

The response would be:

{
  "idDocType": "PASSPORT",
  "country": "GBR",
  "issuedDate": "2015-01-02",
  "number": "40111234567",
  "dob": "2000-02-01",
  "placeOfBirth": "London"
}

Response explained

The response is a JSON file that represents the added document information.

👍

Tip

You can find the imageId of the photo in the X-Image-Id response header.

errors array attributes

warnings array attributes

Supported document types

Specifics of adding company documents

When adding a company document, the request should contain the company document JSON metadata and a document photo or a scanned copy.

📘

Note

Do not send documents of individuals (e.g. beneficiary identity documents) to a company applicant profile for check results consistency.

Request attributes and element fields

The following section includes the attributes and element fields that are specific for company documents.

Request headers

Request arguments

Form data

Request metadata body part fields

Example request

curl -X POST \
  'https://api.sumsub.com/resources/applicants/5e9412223cc1813b4db0b0e3/info/idDoc' \
  -H 'content-type: multipart/form-data' \
  -F 'metadata={"idDocType":"COMPANY_DOC","country":"GBR"}' \
  -F 'content={path to file (file contents)}'

Supported company document types

The tables below include the company document types and subtypes that are supported for company verification.

Supported idDocTypes for company verification

Supported idDocSubTypes for COMPANY_DOC:

Response

The response is a JSON file that represents the document information added to the company profile.

📘

Note

If you need to know the imageId of the photo, you can find it in the response header X-Image-Id.

Example response

{
  "idDocType": "COMPANY_DOC",
  "country": "USA"
}