Requests and responses

Every IDscan Core endpoint works the same way. This page covers what they share; the API reference covers each endpoint’s own fields.

Base addresses

Each service has an address in each region. Use the region your account was set up in.

Service	EU	US
Document Verification	https://verification-v2-eu.core.idscan.cloud	https://verification-v2-us.core.idscan.cloud
Liveness and biometrics	https://liveness-v2-eu.core.idscan.cloud	https://liveness-v2-us.core.idscan.cloud
Face Match	https://facematch-v2-eu.core.idscan.cloud	https://facematch-v2-us.core.idscan.cloud

The endpoint path follows the base address, for example https://verification-v2-eu.core.idscan.cloud/VerifyDocument.

Requests

• Every endpoint is a POST.
• The body is multipart/form-data: image files and text fields, one part each. Field names are case-sensitive and are listed on each endpoint’s reference page.
• Images are sent as files (JPEG or PNG). Endpoints that take an encrypted capture packet, such as EnhancedLiveness, take the packet produced by the capture SDK as a file.
• Most checks come in two forms. The plain endpoint (/Liveness) takes the image itself. The endpoint ending in /id (/Liveness/id) takes the identifier of an image the service has already received, so you can run a second check on the same image without uploading it again. An unknown identifier returns 404.
• Send a token in the Authorization header, and your own reference in the x-correlation-id header or the CorrelationId field.

Responses

• A successful call returns 200 with a JSON body. 200 means the call worked; whether the document, selfie or face comparison passed is in the body, for example in validationInfo and documentScore for a document, or the score for a liveness or face match check.
• Scores are explained on each endpoint’s reference page. For example, the passive liveness score runs from 0 to 100 with 50 and above a pass, and the face match score runs from 0 to 1 with 0.8 and above a match.
• Every response, including an error, carries correlationId.

Status codes

Code	Meaning	What to do
200	The call succeeded. The result is in the body.	Read the result.
204	The call succeeded but there is nothing to return, for example no face to extract from a packet.	Check the input.
400	A field is missing or a value is not allowed.	Read the errors list in the body and check the field against the reference page.
401	The token is missing, expired or not valid for this service or region.	Get a fresh token. See Authentication.
404	The identifier sent to an /id endpoint is not known to the service.	Send the image itself, or check the identifier.
409	The provider chosen for document verification is not supported.	Check the PROVIDER_NAME configuration.
500	The service failed while processing the request.	Contact GBG support with the correlationId.
503	A downstream service is temporarily out of capacity.	Wait, then retry.

Error responses

A 400, 500 or 503 response has this body:

{
  "correlationId": "<the reference you sent>",
  "errorMessage": "<what went wrong>",
  "errors": ["<one entry per problem found>"]
}