Add ID document

Adds an identification document to be verified.

Overview

Use this method to add ID documents to verification.

The method gets a multipart form:

  • Document JSON metadata.
  • [Optionally] A document photo.

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 might 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

errors array attributes

NameDescription
forbiddenDocumentUnsupported or unacceptable type/country of document.
differentDocTypeOrCountryDocument type or country does not match those sent as metadata and the recognized type is forbidden by the 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 presented.
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.
Language
Authorization
Header
Click Try It! to start a request and see the response here!