Document Verification API

identity verification v1.0.0 mdx

API Endpoints for Document Verification

API Version

Version: 1.0.0

API Base URL

https://api-umbrella.io/api/services

Document Verification

Endpoint: /document/verification/
Method: POST
Description: This endpoint verifies the identity of a person based on the provided document images (front and back). It returns a verification result with status, reasons, and personal details.
Authorization: Bearer Token

Request Body:

{
  "country": "DEU",
  "idType": "PASSPORT", // or ID_CARD, other supported document types
  "documentFrontRawImage": "url_or_base64_encoded_image",
  "documentBackRawImage": "url_or_base64_encoded_image", // Optional
  "docType": "url" // or "base64" depending on the image format
}

Supported documents

PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, RESIDENCE_PERMIT

Request fields

Field	Required	Description
country	Yes	ISO 3166-1 alpha-3 country code
idType	Yes	Type of the provided ID. Allowed values: PASSPORT, DRIVING_LICENSE, ID_CARD, RESIDENCE_PERMIT, VISA
documentFrontRawImage	Yes	Base64 encoded image of ID front side or a URL
documentBackRawImage	Yes	Base64 encoded image of ID back side or a URL. Optional for single-sided documents like PASSPORT
docType	Yes	URL or Base64, depending on image format

Response fields

Parameter	Type	Description
status	string	State of the service: Success or Fail
verification	object	Contains details about the verification process
acceptanceTime	string	Initial timestamp in the format `YYYY-MMDDThh:mm:ss.SSSZ`
code	int	Corresponding status code. Possible values: Started (7001), Submitted (7002), Approved (9001), Declined (9102), Resubmission (9103), Expired/Abandoned (9104), Review (9121)
decisionTime	string	Timestamp corresponding to the moment of the final decision in the format `YYYY-MMDDThh:mm:ss.SSSZ`
merchantScanReference	string	Validation reference number
ScanReference	string	Internal reference provided in the start status
status	string	Status of the document validation process. Possible states: Started, Submitted, Approved, Declined, Resubmission, Expired/Abandoned, Review
reason	string	Description of the reason for document rejection (status declined). Null if status approved
reasonCode	int	Code associated with the reason for rejection. Null if status approved
Document	object	Contains document-related information
type	string	Type of document. Possible values: PASSPORT, DRIVING_LICENSE, ID_CARD, VISA, UNSUPPORTED
country	string	Issuing country code in ISO 3166-1 alpha-3 format
number	string	Document number
validUntil	string	Document expiry date
person	object	Contains personal information
firstName	string	User's first name
lastName	string	User's last name
idNumber	string	User's document number
gender	string	Gender
dateOfBirth	string	Date of birth in the format `YYYY-MM-DD`

Common Errors

Error Code	Description
401 Unauthorized	Invalid or missing Bearer token.
400 Bad Request	Missing required fields or invalid data format.
404 Not Found	Document type or country is not supported.

Example implementation

Request Body:

CURL

curl
--location --globoff '{{apiUrl}}/document/verification/' \
--header 'Content-Type: application/json' \
--data {
    "country": "AUT",
    "idType": "ID_CARD",
    "docType: "Base64"
    "documentFrontRawImage": "https://upload.wikimedia.org/wikipedia/commons/0/0e/New_Austrian_ID_Card_%282021%29.png",
    "documentBackRawImage": "https://upload.wikimedia.org/wikipedia/commons/5/53/New_Austrian_ID_Card_%28Backside%29_%282021%29.png"
    }

Response:

JSON

  {
  "status": "success",
  "verification": {
      "scanReference": "2829f9e3-9ab2-4fc9-879a-d4cca74d0a19",
      "code": 9102,
      "person": {
          "gender": null,
          "idNumber": null,
          "lastName": "MUSTERFRAU",
          "firstName": "MARIA",
          "dateOfBirth": "1981-12-31"
      },
      "reason": "Suspicious behaviour",
      "status": "declined",
      "document": {
          "type": "ID_CARD",
          "number": "PA1234567",
          "country": "AUT",
          "validUntil": "2031-08-01"
      },
      "reasonCode": 105,
      "merchantScanReference": "680f8ef8-3ff5-46ee-a04f-97182d889dfV",
      "decisionTime": "2024-11-18T21:44:52.254554Z",
      "acceptanceTime": "2024-11-18T21:44:45.858409Z"
  }
  }

Reason Codes and Descriptions

Code	Description
101	Physical document not used
102	Suspected document tampering
103	Person showing the document does not appear to match document photo
105	Suspicious behaviour
106	Known fraud
108	Velocity/abuse duplicated end-user
109	Velocity/abuse duplicated device
110	Velocity/abuse duplicated ID
112	Restricted IP location
113	Suspicious behaviour - Identity Farming
120	Person on the portrait does not appear to match reference photo
121	User ID missing
122	No reference found
123	Unable to pass registry checks
126	Potential PEP match
127	Face match with blocklist
203	Full document not visible
502	Multiple parties present in session
503	Attempted deceit
504	Attempted deceit, device screen used
505	Attempted deceit, printout used
507	Presented document tampered, data cross reference
508	Presented document tampered, document similarity to specimen
509	Person showing the document does not match document photo
510	Presented document type not supported
511	Presented document expired
515	Attempted deceit, device screen used for face image
526	Attempted deceit, photos streamed
527	Unable to collect proof of address data
528	Proof of address issue date too old
530	Person is under 13 years old
531	Person is under 14 years old
532	Person is under 16 years old
533	Person is under 18 years old
534	Person is under 20 years old
535	Person is under 21 years old
536	Person is under 25 years old
537	Unable to perform document media portrait cropping
539	Resubmission limit exceeded
540	Low confidence score for the session
541	Name on document does not match with name in session initialization data
542	Unable to validate CPF
543	Reference face image has poor quality
544	Registry did not respond
545	Reference image missing
546	Face image quality insufficient
547	Face missing
548	Attempted deceit, with face reference missing
549	NFC validation failed
602	Presented document type not supported
603	Video missing
605	Face image missing
606	Face is not clearly visible
608	Document front missing
609	Document back missing
614	Document front not fully in frame
615	Document back not fully in frame
619	Document data not visible
620	Presented document expired
621	Document annulled or damaged
625	Unable to collect surname
626	Unable to collect first names
627	Unable to collect date of birth
628	Unable to collect issue date
629	Unable to collect expiry date
630	Unable to collect gender
631	Unable to collect document number
632	Unable to collect personal number
633	Unable to collect nationality
634	Unable to collect home address
635	Document and face image missing
636	Presented document not real, screen used
637	Presented document not real, printout used
640	Person did not give consent
641	Multiple Faces Detected
642	Multiple Documents Uploaded
643	Unable to crop face image from a document front
644	Unable to collect Identificador de Ciudadano (INE)
645	Resubmit - Unable to collect OCR (IFE)
646	Unable to estimate age
647	Document not recognised
648	Technical issues
649	Unable to collect foreigner information
650	Unable to collect process number
651	Unable to collect occupation information
652	Unable to collect employer information
653	Unable to collect residence permit type
654	Unable to collect driver's license number
655	Unable to collect additional name
657	Open passport image missing
662	Unable to collect document remarks
1001	Query ID must be between 20 and 40 symbols
1002	Query ID must be a valid UUID V4
1003	Query ID must be unique, it has already been used.
1102	Mandatory parameters are missing from the request.
1104	Request includes invalid parameters.
1201	Invalid timestamp. Timestamp must not be older than one hour
1202	Timestamp format is incorrect. YYYY-MM-DDTHH:MM:S+Timezone Offset
1203	Invalid ISO 8601 date. Date needs to be in format YYYY-MM-DD
1301	Requested features are not supported
1302	Only HTTPS return URLs are allowed
1303	Invalid status
1304	Cannot transition to "$STATUS" status
1308	ID number is missing
1309	SSN validation requires person firstName + lastName OR fullName to be provided
1310	SSN validation requires person.dateOfBirth or address data to be provided
1400	Image data not found
1401	Image is not in valid base64
1402	Image context is not supported
1403	Image property is missing
1500	vendorData field cannot be more than 1000 symbols
1501	vendorData must be a string
2003	Date of birth is not a valid date
2101	Document number has to be between 6 and 9 characters
2102	Document number may contain only characters and numbers A-Z, 0-9
2103	Document type is not supported
2104	Document from provided country is not supported