Document validation Start V2

Start the morphological validation process for identity documents by sending the document images, country and type of document to analyze.

Endpoint

POST /verify/documentValidation/v2/start

Headers

Name	Type	Required	Description
x-api-key	string	Yes	Access authorization API Key.
family	string	No	Value: Onboarding. Required with the Tracking service.

All calls to the Endpoints for Tracking with Identity Platform must contain the header family.

Request body

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
country	string	Yes	Country code ISO 3166-1 alpha-3.
idType	string	Yes	Document type provided. Possible values: PASSPORT, DRIVING_LICENSE, ID_CARD, RESIDENCE_PERMIT, VISA
documentFrontRawImage	string	Yes	Image encoded in Base64, open or tokenized, on the front side of the document.
documentBackRawImage	string	No	Image encoded in Base64, open or tokenized, on the back side of the document. Optional for single-sided documents such as PASSPORT.
tokenRawFrontDocument	string	No	Image Token tokenized from the front side of the document, generated by the SDK Mobile/Web. Alternative to documentFrontRawImage when working with tokenized images.
tokenRawBackDocument	string	No	Image Token tokenized from the back side of the document, generated by the SDK Mobile/Web. Alternative to documentBackRawImage when working with tokenized images.
merchantIdScanReference	string	No	Custom reference for the operation. Maximum length: 100 characters.
documentRawImageMimeType	string	No	MIME type of the image. Possible values: image/png, image/jpeg
tracking	object	No	Object representing the required tracking information.
tracking.extraData	string	No	Token generated by the SDK Mobile/Web. It contains tokenized tracking information with the Platform.
tracking.operationId	string	No	Operation identifier generated by the SDK Mobile/Web.

Document images can be sent in two ways: as an image encoded in Base64 (documentFrontRawImage / documentBackRawImage) or as an image tokenized generated by the SDK (tokenRawFrontDocument / tokenRawBackDocument). Use one or the other depending on the capture mode.

Request example

{
  "country": "ESP",
  "idType": "ID_CARD",
  "documentRawImageMimeType": "image/jpeg",
  "documentFrontRawImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABC...",
  "documentBackRawImage": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABC...",
  "merchantIdScanReference": "custom-ref-123",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Example request with tokenized images

{
  "country": "ESP",
  "idType": "ID_CARD",
  "documentRawImageMimeType": "image/jpeg",
  "tokenRawFrontDocument": "BQABAQFront9kLmPqYf7R...",
  "tokenRawBackDocument": "BQABAQFBack9kLmPqYf7R...",
  "merchantIdScanReference": "custom-ref-123",
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Responses

200 Success

Response parameters

Parameter	Type	Description
timestamp	string	UTC timestamp of the response in format ISO 8601.
scanReference	string	Reference number for each scan.
type	string	⚠️ Value deprecated. Will be removed in future versions.

Response example

{
  "timestamp": "1970-01-01T00:00:00.000Z",
  "scanReference": "fe294c25-17e1-4d98-a958-710edbf00064",
  "type": "1"
}

400 Bad Request

{
  "status": 400,
  "title": "Bad Request",
  "detail": "Invalid request.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Unauthorized

{
  "message": "Unauthorized"
}

403 Forbidden

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Bad Gateway

{
  "status": 502,
  "title": "Bad Gateway",
  "detail": "Server got an invalid response.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "Endpoint request timed out"
}