Add ID document

Adds an identification document to the verification flow.

Table of contents

Overview

Use this method to:

The method gets a multipart form:

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

If a document with the same idDocType and country already exists, the new data will be merged with the existing one. Any existing data will be overwritten if it is also 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.

For adding 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, errors or warnings array will present.

If you happen to encounter an error 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 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 a 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 array 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

NameDescription
forbiddenDocumentDocument type or country is unsupported or unacceptable.
differentDocTypeOrCountryDocument type or country does not match the data sent as metadata and the recognized type is forbidden by the document settings.
missingImportantInfoNot all required document data can be recognized.
dataNotReadableThere is no data to be recognized from the image.
expiredDocDocument validity date is expired.
documentWayTooMuchOutsideParts of the document are cropped.
noIdDocFacePhotoFace is not clearly visible on the document.
selfieFaceBadQualityFace is not clearly visible on the selfie.
screenRecaptureImage might be a photo of the screen.
screenshotImage is a screenshot.
sameSidesImage of the same side of the document was uploaded as front and back sides.
shouldBeMrzDocumentSent document type should have an MRZ, but there is no readable MRZ on the image.
shouldBeDoubleSidedTwo sides of the sent document should be submitted.
shouldBeDoublePagedThe full double-page of the document (usually, two main passport pages) are required.
documentDeclinedBeforeThe same image was uploaded and declined earlier in the same applicant.

warnings array attributes

NameDescription
badSelfieMake sure that your face and the photo in the document are clearly visible.
dataReadabilityMake sure that information in the document is easy to read.
inconsistentDocumentMake sure that all uploaded photos are of the same document.
maybeExpiredDocYour document appears to be expired.
documentTooMuchOutsideMake sure that the document completely fits the photo.

Supported document types

ValueDescription
ID_CARDAn ID card.
PASSPORTA passport.
DRIVERSA driving license.
RESIDENCE_PERMITResidence permit or registration document in the foreign city/country.
UTILITY_BILLProof of address document. Check here for the full list of acceptable documents as UTILITY_BILL.
SELFIEA selfie with a document.
VIDEO_SELFIEA selfie video (can be used in WebSDK and MobileSDK).
PROFILE_IMAGEA profile image, i.e. avatar (in this case, no additional metadata should be sent).
ID_DOC_PHOTOPhoto from an ID document like a photo from the passport (In this case, no additional metadata should be sent).
AGREEMENTAn agreement, e.g. for processing personal information.
CONTRACTA contract.
DRIVERS_TRANSLATIONTranslation of the driving license required in the target country.
INVESTOR_DOCA document from an investor, e.g. documents which disclose assets of the investor.
VEHICLE_REGISTRATION_CERTIFICATECertificate of vehicle registration.
INCOME_SOURCEA proof of income.
PAYMENT_METHODEntity confirming payment (like bank card, crypto wallet, etc).
BANK_CARDA bank card, like Visa or Maestro.
COVID_VACCINATION_FORMCOVID vaccination document (may contain the QR code).
OTHERShould be used only when nothing else applies.

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

NameTypeValue
Content-TypeStringmultipart/form-data

Request arguments

NameTypeRequiredDescription
applicantIdStringYesA unique company applicant identifier.

Form data

NameTypeRequiredDescription
metadataObjectYesAn object that represents an ID document.
contentBinaryNoA photo of a document.

Request metadata body part fields

NameTypeRequiredDescription
idDocTypeStringYesDocument type.
idDocSubTypeStringNoSee supported idDocSubTypes for COMPANY_DOC below.
countryStringYesA three-letter code of the country that issued the document.

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

ValueDescription
COMPANY_DOCDefault type of the document for company verification.
TRANSPARENCY_REGISTRY_EXTRACTRecent excerpt from a transparency company registry.
POWER_OF_ATTORNEYPower of attorney.

Supported idDocSubTypes for COMPANY_DOC:

ValueDescription
DIRECTORS_REGISTRYDirectors registry.
STATE_REGISTRYRecent excerpt from a state company registry.
INCUMBENCY_CERTCertificate of incumbency.
PROOF_OF_ADDRESSProof of address. For example, a utility bill, rent contract or an electricity bill.
TRUST_AGREEMENTTrust agreement.
INFORMATION_STATEMENTStatement of information.
INCORPORATION_CERTCertificate of incorporation/registration.
INCORPORATION_ARTICLESMemorandum/articles of incorporation/association/registration.
SHAREHOLDER_REGISTRYShareholder registry.
GOOD_STANDING_CERTCertificate of good standing.
OTHERSubtype for a document when none of above subtypes apply.

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"
}
Language
Authorization
Header
Click Try It! to start a request and see the response here!