Introduction

This is a Service for reading and validating original identity documents.

How it's work?

The user takes an image of his identity document with a mobile device or from a webcam, this image is sent to the LINK Mobility service where it is processed by Optical Character Recognition (OCR).

This processing consists of the reading, extraction and validation of the different technical aspects and security measures that each type of identity document possesses, returning the result of said validation to the company that hires the services.

Environments

URL addresses that you need to use to connect to Link KYC are:

Environment	Host
Production	https://kyc-api.linkmobility.es
Stage	https://kyc-api-stage.linkmobility.es:51443

Authentication

Link Mobility uses OAuth v2 with tokens for authorization. This token-based standard takes advantage of temporary tokens that have access to a resource for a limited time. In our environments, these tokens will only be valid for 60 minutes.

Authorization header will be necessary in request to our API.

Authentication Request

Example Request

POST /auth/token HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json

{
    "user": "{{user}}",
    "password": "{{password}}"
}

URL

/auth/token

Messages should be sent as a HTTP POST request to our system.

Required Fields

Parameter	Type	Description
user	string	Username (provided by Link Mobility)
password	string	Password (provided by Link Mobility)

required fields are bold

Authentication Response

200 Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "token": "eyJhbGciOiJodHRw...qZ2aG2Y_I",
    "scopes": [
        "kyc.idVeriication.auto",
        "kyc.facecomparison.auto",
        "kyc.idVerification.manual",
        "kyc.facecomparison.manual",
        "kyc.certification"
    ],
    "expiresIn": 3600,
    "token_type": "bearer"
}

401 Response Example ( Unauthorized )

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

500 Response Example ( Internal Server Error )

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
    "code": "003",
    "message": "Validation Error: Invalid credentials"
}

The authentication response returns the token that will be used in the requests, the token expiration (in seconds), the scopes provided within the token and the type of token to be indicated in the header.

Returned Fields

Parameter	Type	Description
token	string	Token to be submitted with any subsequent API request
scopes	string (array)	Scopes included in the token
expiresIn	Numeric	Duration of token validity measured in seconds
token_type	string	type of token to be indicated in the header Authorization

Ping

It is a help operation and can be used to check API availability.

Ping Request

Example Request

POST /ping HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json

URL

ping

Ping Response

200 Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "900c131c-13a2-46cf-9e0d-2634f31e8efd",
    "service": "KYC API",
    "version": "1.3.3.0",
    "release": "1.3.3.20210420",
    "env": "Production",
    "date": "2021-01-01 12:00:00 +00:00"
}

503 Service Unavailable

HTTP/1.1 503 Service Unavailable
Content-Type: application/json; charset=utf-8

Returned Fields

Parameter	Type	Description
id	string	An unique identifier per request
service	string	Name of the API Service. (Always return "KYC API")
version	string	API version
release	string	API release version
env	string	Environment
date	string	Date and time of the request in (Format: yyyy-MM-dd HH:mm:ss zzz)

Identity

Identity verify allows you to read, extract and validate an identity document automatically or manually. A facial comparison can be performed to validate that the image of a person matches the image of the identity document.

We also provides the possibility of certifying the validation of the identity document by means of a certified document with a time stamp.

One and two sided identity documents and passports are accepted.

Verify Request

Example request (One image side)

POST /identity/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    }
  ],
  "expeditorCountry": "ES",
  "certify": false,
  "certifyCallback": ""
}

Example request (Two image side)

POST /identity/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": false,
  "certifyCallback": ""
}

Example request (One image side + Certification)

POST /identity/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

Example request (Two image side + Certification)

POST /identity/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

Example request (Two image side + Face Comparison + Certification)

POST /identity/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q==",
      "faceImage": "iVBORw0KGgoAAAANSUhE...I6jMG3AAAAAElFTkSuQmCC"
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

Example request - Manual ID verification (Two image side + Face Comparison + Certification)

POST /identity/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q==",
      "faceImage": "iVBORw0KGgoAAAANSUhE...I6jMG3AAAAAElFTkSuQmCC"
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a",
  "manualVerification": true,
  "manualVerificationCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

URL

/identity/verify

Messages should be sent as a HTTP POST request to our system.

Required Fields

Parameter	Type	Description
id	string	Request identifier
images	object (array)	List of images corresponding to the identity document
content	string (base64)	Image content of the identity document.
faceImage	string (base64)	Content of the face image. The face image will be compared with the image content of the identity document
expeditorCountry	string	Indicates the expeditor country of the identity document.
certify	boolean	Indicate if you wants certify the operation
certifyCallback	string	Indicate the URL callback to receive the certificate file. Required if you mark certify to true. If certify ist marked as true and the certifyCallback is null or empty, the system get the default URL from user settings
manualVerification	boolean	Indicate if you wants forces to Manual ID verification process. Default value: false By default all requests will be processed through the automatic process.
manualVerificationCallback	string	Indicate the URL callback to receive the manual ID Verification result. Required if you mark manualVerification to true. If manualVerification ist marked as true and the manualVerificationCallback is null or empty, the system get the default URL from user settings

required fields are bold

Verify Response

200 Auto ID Verification Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "idVerification": {
        "status": "Completed",
        "process": "Automatic",
        "result": "Ok",
        "warning": "",
        "fields": [
            {
                "type": "Normal",
                "code": "TYPE",
                "value": "IDENTITY",
                "description": "TYPE"
            },
            {
                "type": "Normal",
                "code": "SIDE",
                "value": "1",
                "description": "SIDE"
            },
...
            {
                "type": "Normal",
                "code": "QUALITY_IMAGE_BLURRING",
                "value": "IQ_GOOD 11%",
                "description": "QUALITY_IMAGE_BLURRING"
            },
            {
                "type": "Normal",
                "code": "ICAR_RESULT_DOCUMENT_ID",
                "value": "IDESPC1",
                "description": "ICAR_RESULT_DOCUMENT_ID"
            }
        ]
    },
    "certification": {
        "status": "Processing"
    }
}

200 Manual ID Verification Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "d656cd3a-b457-4371-929f-e674b299cd73",
    "idVerification": {
        "status": "Processing",
        "process": "Manual"
    }
}

401 Response Example ( Unauthorized )

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

400 Response Example ( Bad Request )

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "code": "003",
    "message": "Validation Error: There are images with invalid base64 format"
}

500 Response Example ( Internal Server Error )

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "code": "001",
    "message": "Unknown Error: Error processing request"
}

Returned Fields

Parameter	Type	Description
id	string	Request Identifier
idVerification	object	contains all the information related to the validation of the identity document
status	string	Operation status (Service Operation Status)
process	string	Indicates if the validation was done in Automatic or Manual process. Values: "Automatic" or "Manual"
result	string	Result of the validation (ID Verification Result Codes)
warning	string	Warning message when Result has a NotCorrect or NotProcessed result
fields	object (array)	List containing all fields and validations of the document. The number or type of these fields depends on the document
type	string	Type of the field. Values: "Normal", "Validation"
code	string	Identifier of the field
value	string	Value of the field
description	string	Field description and usually the same as code.
certification	object	Indicate if you wants certify the operation
status	string	Operation status. The result of this operation wil send by callback (Service Operation Status)

Verify Request v2

Example request (One image side)

POST /identity/v2/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    }
  ],
  "expeditorCountry": "ES",
  "certify": false,
  "certifyCallback": ""
}

Example request (Two image side)

POST /identity/v2/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": false,
  "certifyCallback": ""
}

Example request (One image side + Certification)

POST /identity/v2/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

Example request (Two image side + Certification)

POST /identity/v2/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q=="
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

Example request (Two image side + Face Comparison + Certification)

POST /identity/v2/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q==",
      "faceImage": "iVBORw0KGgoAAAANSUhE...I6jMG3AAAAAElFTkSuQmCC"
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

Example request - Manual ID verification (Two image side + Face Comparison + Certification)

POST /identity/v2/verify HTTP/1.1
Host: {{environment_host}}
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{
  "id": "00627e53-800b-4e6d-86ff-b933e2940a04",
  "images": [
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...bufv0YR5VoD/2Q==",
      "faceImage": "iVBORw0KGgoAAAANSUhE...I6jMG3AAAAAElFTkSuQmCC"
    },
    {
      "content": "/9j/4AAQSkZJRgABAQEAAA...0tWYYuvUt7NaLsAP/Z"
    }
  ],
  "expeditorCountry": "ES",
  "certify": true,
  "certifyCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a",
  "manualVerification": true,
  "manualVerificationCallback": "https://webhook.site/8696d970-fa21-4561-bdbb-4d4f716d923a"
}

URL

/identity/v2/verify

Messages should be sent as a HTTP POST request to our system.

Required Fields

Parameter	Type	Description
id	string	Request identifier
images	object (array)	List of images corresponding to the identity document
content	string (base64)	Image content of the identity document.
faceImage	string (base64)	Content of the face image. The face image will be compared with the image content of the identity document
expeditorCountry	string	Indicates the expeditor country of the identity document.
certify	boolean	Indicate if you wants certify the operation
certifyCallback	string	Indicate the URL callback to receive the certificate file. Required if you mark certify to true. If certify ist marked as true and the certifyCallback is null or empty, the system get the default URL from user settings
manualVerification	boolean	Indicate if you wants forces to Manual ID verification process. Default value: false By default all requests will be processed through the automatic process.
manualVerificationCallback	string	Indicate the URL callback to receive the manual ID Verification result. Required if you mark manualVerification to true. If manualVerification ist marked as true and the manualVerificationCallback is null or empty, the system get the default URL from user settings

required fields are bold

Verify Response v2

200 Auto ID Verification Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "idVerification": {
        "status": "Completed",
        "process": "Automatic",
        "documentInfo": {
            "result": "Ok",
            "warning": "",
            "fields": [
                {
                    "type": "Normal",
                    "code": "TYPE",
                    "value": "IDENTITY",
                    "description": "TYPE"
                },
                {
                    "type": "Normal",
                    "code": "SIDE",
                    "value": "1",
                    "description": "SIDE"
                },
    ...
                {
                    "type": "Normal",
                    "code": "QUALITY_IMAGE_BLURRING",
                    "value": "IQ_GOOD 11%",
                    "description": "QUALITY_IMAGE_BLURRING"
                },
                {
                    "type": "Normal",
                    "code": "ICAR_RESULT_DOCUMENT_ID",
                    "value": "IDESPC1",
                    "description": "ICAR_RESULT_DOCUMENT_ID"
                }
            ]
        },
        "faceComparisonInfo": {
            "approval": "NOT_APPROVED",
            "findings": {
                "faceComparisonApproval": "NOT_MATCH"
            }
        }
    },
    "certification": {
        "status": "Processing"
    }
}

200 Manual ID Verification Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "d656cd3a-b457-4371-929f-e674b299cd73",
    "idVerification": {
        "status": "Processing",
        "process": "Manual"
    }
}

401 Response Example ( Unauthorized )

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

400 Response Example ( Bad Request )

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "code": "003",
    "message": "Validation Error: There are images with invalid base64 format"
}

500 Response Example ( Internal Server Error )

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "code": "001",
    "message": "Unknown Error: Error processing request"
}

Returned Fields

Parameter	Type	Description
id	string	Request Identifier
idVerification	object	contains all the information related to the validation of the identity document and face comparison
status	string	Operation status (Service Operation Status)
process	string	Indicates if the validation was done in Automatic or Manual process. Values: "Automatic" or "Manual"
documentInfo	object	Contains all the information about the identity document
result	string	Result of the validation (ID Verification Result Codes)
warning	string	Warning message when Result has a NotCorrect or NotProcessed result
fields	object (array)	List containing all fields and validations of the document. The number or type of these fields depends on the document
type	string	Type of the field. Values: "Normal", "Validation"
code	string	Identifier of the field
value	string	Value of the field
description	string	Field description and usually the same as code.
faceComparisonInfo	object	Contains all the information about the face comparison
approval	string	An overall service approval result taking both face comparison and face liveness into account. APPROVED: The value will be returned in case faceComparisonApproval is MATCH and faceLivenessApproval is LIVE. Note, if faceLiveness is not enabled, then only faceComparisonApproval is taken into account. NOT_APPROVED: The value will be returned in case faceComparisonApproval is NOT_MATCH or faceLivenessApproval is NOT_LIVE.
findings	object	The following fields are related to the overall findings that resulted from the processing of the face comparison.
faceComparisonApproval	string	Service approval result containing auto face comparison judgement. MATCH: The value will be returned in case selfie photo matches portrait image of document holder. NOT_MATCH: The value will be returned in case selfie photo does not match portrait image of document holder.
faceLivenessApproval	string	Service approval result containing face liveness detection judgement. LIVE: The value will be returned in case selfie photo is from a live person. NOT_LIVE: The value will be returned in case selfie is not from a live person -- e.g. if the selfie is a picture of a picture
reasons	string (array)	The reasons that the service is unable to complete face comparison and/or face liveness detection. FACE_CROPPED_SELFIE_IMAGE: The complete face is not present in the selfie image. FACE_NOT_DETECTED_REFERENCE_IMAGE: The face could not be detected in the reference image. FACE_NOT_DETECTED_SELFIE_IMAGE: The face could not be detected in the selfie image. FACE_TOO_CLOSE_SELFIE_IMAGE: The face in the selfie image is too close to the camera. FACE_TOO_FAR_SELFIE_IMAGE: The face in the selfie image is too far from the camera. FACE_ANGLE_TOO_LARGE_SELFIE_IMAGE: The angle between the face and camera is too large in the selfie image. QUALITY_TOO_LOW_SELFIE_IMAGE: The selfie has failed the image quality check. TOO_MANY_FACES_SELFIE_IMAGE: More than one face was detected in the selfie image.
certification	object	Indicate if you wants certify the operation
status	string	Operation status. The result of this operation wil send by callback (Service Operation Status)

Migration to v2

What's new

In v2 we improve the Face Comparison service with more details in the response. Due to this, in v2 the info of the ID card validation and face comparison are returned separately

Breaking changes

The breaking change only is affected the identity verify response

In v2 response there are two new objects returned in /identity/v2/verify:

documentInfo: Contains all the information about the identity document. It's maintain the same schema as in the v1 with the sames fields and values. But it's remove the fields TEST_FACE_RECOGNITION_VALUE and TEST_FACE_RECOGNITION_RATIO. The Face Comparison info is returned in the faceComparisonInfo object.

faceComparisonInfo: Contains all the information about the face comparison with new details.

How to handle the v2 response

ID verification

The properties status and process are the sames and shuold be handle as same as v1

Identity document validation

The identity document validation info move into the new object documentInfo. The info inside documentInfo is the same as v1 in idVerification. Note that the fields TEST_FACE_RECOGNITION_VALUE and TEST_FACE_RECOGNITION_RATIO are removed.

Face Comparison info

In the v1 the face comparison info is returned in the fields TEST_FACE_RECOGNITION_VALUE and TEST_FACE_RECOGNITION_RATIO. Now, in v2 the face comparison is returned in the new object faceComparisonInfo. The schema of the face comparison info in v2 is new and has more details, please refer to Verifiy Response v2 to see the new schema and data. When you use the v2 you should replace your business logic to handle the new data for the face comparison.

Support

Please, contact with our support team for any futher information. soporte.es@linkmobility.com

Certification

In this module you can manage the certificate files

Get Certificate File Request

Example request (Two image side + Face Comparison + Certification)

GET /certificate/b2820098-04a9-47ef-9d5f-c668e016a596 HTTP/1.1
Host: {{environment_host}}
Authorization: Bearer {{auth_token}}

URL

/identity/{{request_id}}

Required Fields

Parameter	Type	Description
request_id	string	Request identifier

Get Certificate File Response

200 Response Example ( OK )

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
    "content": "JVBERi0xLjQKJeLjz9MKMSAwI....VmCjEwNzkyMAolJUVPRgo="
}

401 Response Example ( Unauthorized )

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

404 Response Example ( Not Found )

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

Returned Fields

Parameter	Type	Description
id	string	Request Identifier
content	string (base64)	Content of the certificate file in base64 format

Callback Response

Callback service allows receiving updates about operations (ID Verification Certification). Endpoint URL is typed into the request or in the user settings. After the new event, KYC generates POST request with data to user endpoint.

Requests may be generated from following IP addresses:

• Primary: 82.98.137.60
• Secondary: 217.75.233.139 , 212.170.103.155

Please keep it in mind to open the firewall on your side

Calbback Format

Parameter	Type	Description
id	string	Request Identifier
service	string	Operation service name. Values: "Certification"
status	string	Operation status (Service Operation Status)
data	object	Contains the data corresponding to the operation event

Certification callback

Callback Example

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
  "service": "Certification",
  "status": "Completed",
  "data": {
    "urlCertificateFile": "{{environment_host}}/certificate/b2820098-04a9-47ef-9d5f-c668e016a596"
  }
}

This callback is triggered when a certification operation is completed succesfully or when there was an error.

Fields sent

Parameter	Type	Description
id	string	Request Identifier
service	string	Operation service name. Values: "Certification"
status	string	Operation status (Service Operation Status)
data	object	Contains the data corresponding to the Certification operation
urlCertificateFile	string	URL to download the certificate file. This URL must call it with autohorization header

Manual ID Verification callback

Callback Example "APPROVED"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
  "service": "ManualIDVerification",
  "status": "Completed",
  "data": {
    "documentInfo": {
      "acceptance": {
          "result": "ACCEPTED"
        },
        "findings": {
          "documentApproval": "APPROVED",
          "details": {
            "authenticity": {
              "result": "AUTHENTIC"
            },
            "originality": {
              "result": "ORIGINAL"
            },
            "validity": {
              "result": "VALID"
            }
          }
        },
        "extractedData": {
          "documentAttributes": {
            "countryCodeOfIssuance": "ESP",
            "dateOfExpiry": "1963-10-31",
            "dateOfIssuance": "1963-10-31",
            "documentNumber": "12345678Z",
            "documentType": "IDENTITY_CARD",
            "issuingAuthority": "",
            "stateOrProvinceOfIssuance": "MAD"
          },
          "personAttributes": {
            "dateOfBirth": "1963-10-31",
            "gender": "M",
            "nationalityCode": "ARG",
            "personalGovernmentId": "123435534",
            "placeOfBirth": "BUENOS AIRES"
          },
          "name": {
            "firstSurname": "LUIS ALBERTO",
            "fullName": "LUIS ALBERTO GARCIA DE TODOS LOS SANTOS",
            "givenNames": "LUIS",
            "secondSurname": "DE TODOS LOS SANTOS",
            "surname": "GARCIA DE TODOS LOS SANTOS"
          },
          "address": {
            "parsedAddress": {
              "addressLine1": "CALLE SIN NOMBRE, 34 23º 17",
              "addressLine2": "28001 MADRID",
              "addressLine3": "",
              "addressLine4": "",
              "city": "MADRID",
              "postalCode": "28001",
              "stateOrProvince": "MAD"
            },        
            "unparsedAddress": {
              "addressLine1": "CALLE SIN NOMBRE, 34 23º 17",
              "addressLine2": "28001 MADRID",
              "addressLine3": "",
              "addressLine4": ""
            }
          }
        } 
    },
    "faceComparisonInfo": {
      "acceptance": {
        "result": "ACCEPTED"
      },
      "findings": {
        "faceComparisonApproval": "MATCH"
        "faceLivenessApproval": "LIVE"
      }
    }
  }
}

Callback Example "NOT_APPROVED"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
  "service": "ManualIDVerification",
  "status": "Completed",
  "data": {
    "documentInfo": {
      "acceptance": {
          "result": " ACCEPTED"
        },
        "findings": {
          "documentApproval": "NOT_APPROVED",
          "details": {
            "authenticity": {
              "result": "NOT_AUTHENTIC",
              "reasons": [
                "EVIDENCE_OF_FORGERY_BIODATA_FONTS",
                "EVIDENCE_OF_FORGERY_MRZ_FONTS",
                "EVIDENCE_OF_FORGERY_PHOTO_ZONE",
                "EVIDENCE_OF_FORGERY_SIGNATURE"
              ]
            },
            "originality": {
              "result": "NOT_ORIGINAL",
              "reasons": [
                "EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY",
                "EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE"
              ]
            },
            "validity": {
              "result": "NOT_VALID",
              "reasons": [          
                "EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS",
                "EXPIRED_OR_INVALIDATED"
              ]
            }
          }
        },
        "extractedData": {
          "documentAttributes": {
            "countryCodeOfIssuance": "ESP",
            "dateOfExpiry": "1963-10-31",
            "dateOfIssuance": "1963-10-31",
            "documentNumber": "12345678Z",
            "documentType": "IDENTITY_CARD",
            "issuingAuthority": "",
            "stateOrProvinceOfIssuance": "MAD"
          },
          "personAttributes": {
            "dateOfBirth": "1963-10-31",
            "gender": "M",
            "nationalityCode": "ARG",
            "personalGovernmentId": "123435534",
            "placeOfBirth": "BUENOS AIRES"
          },
          "name": {
            "firstSurname": "LUIS ALBERTO",
            "fullName": "LUIS ALBERTO GARCIA DE TODOS LOS SANTOS",
            "givenNames": "LUIS",
            "secondSurname": "DE TODOS LOS SANTOS",
            "surname": "GARCIA DE TODOS LOS SANTOS"
          },
          "address": {
            "parsedAddress": {
              "addressLine1": "CALLE SIN NOMBRE, 34 23º 17",
              "addressLine2": "28001 MADRID",
              "addressLine3": "",
              "addressLine4": "",
              "city": "MADRID",
              "postalCode": "28001",
              "stateOrProvince": "MAD"
            },        
            "unparsedAddress": {
              "addressLine1": "CALLE SIN NOMBRE, 34 23º 17",
              "addressLine2": "28001 MADRID",
              "addressLine3": "",
              "addressLine4": ""
            }
          }
        } 
      },
    "faceComparisonInfo": {
      "acceptance": {
        "result": "ACCEPTED"
      },
      "findings": {
        "faceComparisonApproval": "NOT_MATCH"
        "faceLivenessApproval": "NOT_LIVE"
      }
    }   
  }
}

Callback Example "REJECTED"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b2820098-04a9-47ef-9d5f-c668e016a596",
  "service": "ManualIDVerification",
  "status": "Completed",
  "data": {
    "documentInfo": {
      "acceptance": {
          "result": " REJECTED",
          "reasons": [
            "GLARE",
            "INCOMPLETE_DOCUMENT",
            "NOT_VISIBLE_FOUR_CORNERS",
            "NOT_VISIBLE_SECURITY_FEATURES",
            "OUT_OF_FOCUS",
            "POOR_CONTRAST",
            "POOR_EXPOSURE",
            "UNCLASSIFIED_DOCUMENT",
            "UNREADABLE_FIELD",
            "UNSUPPORTED_LANGUAGE"
          ]
      }
    },
    "faceComparisonInfo": {
      "acceptance": {
        "result": " REJECTED",
        "reasons": [
          "POOR_CONTRAST",
          "POOR_EXPOSURE",
          "OUT_OF_FOCUS",
          "GLARE",
          "MISSING_SELFIE",
          "MISSING_PORTRAIT",
          "NOT_HUMAN_FACE",
          "PARTIALLY_VISIBLE_HUMAN_FACE",
          "SELFIE_NOT_LIVE",
          "PORTRAIT_IS_FAKE"
        ]
      }
    }
  }
}

Callback Data Structure

    
id
service
status
data
 ├── documentInfo
 |    ├── acceptance
 |    │    ├── result
 |    |    └── reasons
 |    ├── findings
 |    │    ├── documentApproval
 |    |    └── details
 |    |         ├── authenticity
 |    │         |    ├── result
 |    │         |    └── reasons
 |    |         ├── originality
 |    │         |    ├── result
 |    │         |    └── reasons
 |    |         └── validity
 |    │              ├── result
 |    │              └── reasons
 |    └──  extractedData
 |          ├── documentAttributes
 |          |    ├── countryCodeOfIssuance
 |          |    ├── dateOfExpiry
 |          |    ├── dateOfIssuance
 |          |    ├── documentNumber
 |          |    ├── documentType
 |          |    ├── issuingAuthority
 |          |    └── stateOrProvinceOfIssuance
 |          ├── personAttributes
 |          |    ├── dateOfBirth
 |          |    ├── gender
 |          |    ├── nationalityCode
 |          |    ├── personalGovernmentId
 |          |    └── placeOfBirth
 |          ├── name
 |          |    ├── firstSurname
 |          |    ├── fullName
 |          |    ├── givenNames
 |          |    ├── secondSurname
 |          |    └── surname
 |          └── address
 |               ├── parsedAddress
 |               |    ├── addressLine1
 |               |    ├── addressLine2
 |               |    ├── addressLine3
 |               |    ├── addressLine4
 |               |    ├── city
 |               |    ├── postalCode
 |               |    └── stateOrProvince
 |               └── unparsedAddress
 |                    ├── addressLine1
 |                    ├── addressLine2
 |                    ├── addressLine3
 |                    └── addressLine4
 └── faceComparisonInfo
      ├── acceptance
      │    ├── result
      |    └── reasons
      └── findings
           ├── faceComparisonApproval
           └── faceLivenessApproval
    

This callback is triggered when a manual ID Verification operation is completed succesfully or when there was an error.

Fields sent

Parameter	Type	Description
id	string	Request Identifier
service	string	Operation service name. Values: "ManualIDVerification"
status	string	Operation status (Service Operation Status)
data	object	Contains the data corresponding to the Manual ID Verification operation
documentInfo	object	Contains the result of document validation.
acceptance	object	The determination of whether the images submitted were of sufficient quality for a document to be processed. In the event a document is unable to be processed successfully, a status of REJECTED will be returned and the reasons for failure will be included in the reasons field
result	string	The determinition of whether all of the images submitted were deemed acceptable for processing. ACCEPTED: All of the images submitted were deemed acceptable for processing. REJECTED: One or more of the images submitted were deemed not acceptable for processing.
reasons	string (array)	The reasons that a result of REJECTED was returned. GLARE: Rejected due to glare on received document images. INCOMPLETE_DOCUMENT: The number of images submitted did not meet the expected number of images for this specific document. Please make sure you have submitted an image for each page of the document. NOT_VISIBLE_FOUR_CORNERS: One or more of the submitted images could not be processed due to all four corners of the document not being visible. Please retake the images before resubmitting them, mindful of anything that could be blocking the corners of the document from being seen. NOT_VISIBLE_SECURITY_FEATURES: One or more of the submitted images could not be processed due to one or more expected security features not being visible. Please retake the images before resubmitting them, mindful of anything that could be blocking a security feature from being seen. OUT_OF_FOCUS: One or more of the submitted images could not be processed due to the image being out of focus. Please retake the images before resubmitting them. POOR_CONTRAST: One or more of the submitted images could not be processed due to the image having poor contrast. Please retake the images before resubmitting them. POOR_EXPOSURE: One or more of the submitted images could not be processed due to the image having poor exposure. Please retake the images before resubmitting them. UNCLASSIFIED_DOCUMENT: The submitted images could not be classified or are not supported. Please submit only supported documents. UNREADABLE_FIELD: One or more of the submitted images could not be processed due to one or more fields being unreadable. Please retake the images before resubmitting them, mindful of anything that could be blocking a field from being processed. UNSUPPORTED_LANGUAGE: One or more of the submitted images contains a document with a language that we do not support. Please submit only supported documents.
findings	object	The following fields are related to the overall findings that resulted from the processing of the document. This includes the overall document approval and a detailed summary of the authenticity, originality and the validity findings that contributed to the document approval result.
documentApproval	string	The overall document approval determination. APPROVED: The submitted document was processed successfully, and the checks related to authenticity, originality, and validity determined that it should be approved. NOT_APPROVED: The submitted document was processed successfully, but one or more factors related to authenticity, originality, and validity determined that it should not be approved.
details	object	The details of the authenticity, originality, and validity checks that were performed.
authenticity	object	The details of the authenticity checks that were performed.
result	string	The overall authenticity result of the processed document. AUTHENTIC: The processed document was determined to be authentic. NOT_AUTHENTIC: The processed document was determined to be not authentic.
reasons	string (array)	The reasons that a result of NOT_AUTHENTIC was returned. EVIDENCE_OF_FORGERY_BIODATA_FONTS: Manual review of the submitted document indicated that details had been manipulated in the biographical text of the document. EVIDENCE_OF_FORGERY_MRZ_FONTS: Manual review of the submitted document indicated that details had been manipulated in the MRZ section of the document. EVIDENCE_OF_FORGERY_NOT_HUMAN_FACE: The document shows strong evidence of forgery missing a human face on document portrait. EVIDENCE_OF_FORGERY_PHOTO_ZONE: Manual review of the submitted document indicated that there may have been an attempt to manipulate the photo zone of the document.
originality	object	The details of the originality checks that were performed.
result	string	The overall originality result of the processed document. ORIGINAL: The processed document was determined to be original. NOT_ORIGINAL: The processed document was determined to be not original.
reasons	string (array)	The reasons that a result of NOT_ORIGINAL was returned. EVIDENCE_OF_FORGERY_BLACK_AND_WHITE_COPY: Manual review of the submitted document indicated that the image was a black and white copy EVIDENCE_OF_FORGERY_DOCUMENT_STRUCTURE: Manual review of the submitted document indicated that the document structure was not consistent with the known document.
validity	object	The details of the validity checks that were performed.
result	string	The overall validity result of the processed document. VALID: The processed document was determined to be valid. NOT_VALID: The processed document was determined to be not valid.
reasons	string (array)	The reasons that a result of NOT_VALID was returned. EVIDENCE_OF_FORGERY_MRZ_CHECKSUMS: After proofreading of the MRZ by the manual review team, the resultant MRZ failed one or many checksum validations EXPIRED_OR_INVALIDATED: The document is expired due to expiry date or invalidated by issuing authorities due to one or many invalidity markups on the document
extractedData	object
documentAttributes	object	The data extracted from the submitted document. The data returned within extracted data is dependent on the type of document submitted; not all documents supported contain all possible fields.
countryCodeOfIssuance	string	The data extracted from an MRZ field related to the ISO code of the country that issued the document.
dateOfExpiry	string	The data extracted from an MRZ field related to the date of expiry of the document, normalized into the following format: YYYY-MM-DD.
dateOfIssuance	string	The data extracted from an MRZ field related to the date of issuance of the document, normalized into the following format: YYYY-MM-DD.
documentNumber	string	The data extracted from an MRZ field related to the number or identifier of the document.
documentType	string	The type of document that was submitted. Values: PASSPORT DRIVERS_LICENSE IDENTITY_CARD RESIDENCE_PERMIT HEALTH_SERVICES_CARD
issuingAuthority	string	The data extracted from an MRZ field related to the name of the authority or organization that issued the document.
stateOrProvinceOfIssuance	string	The data extracted from an MRZ field related to the name of the state, province, or region that issued the document.
personAttributes	object	The data extracted from the submitted document, specifically from fields that are related to the person to whom the document was issued.
dateOfBirth	string	The data extracted from an MRZ field related to the date of birth of the person to which the document was issued, normalized into the following format: YYYY-MM-DD.
gender	string	The data extracted from an MRZ field related to the gender of the person to which the document was issued, normalized into one of the following values: M (male) F (female) N/B (non binary).
nationalityCode	string	The data extracted from an MRZ field related to the ISO country code of the nationality of the person to which the document was issued.
personalGovernmentId	string	The data extracted from an MRZ field related to any government identification number of the person to which the document was issued.
placeOfBirth	string	The data extracted from an MRZ field related to the place of birth of the person to which the document was issued.
name	object	The data extracted from the submitted document, specifically from fields that are related to the name of whom the document was issued.
fullName	string	The data extracted from an MRZ field related to the full name of the person to which the document was issued.
givenNames	string	The data extracted from an MRZ field related to the given names of the person to which the document was issued.
firstSurname	string	The data extracted from an MRZ field related to the first surname of the person to which the document was issued.
secondSurname	string	The data extracted from an MRZ field related to the second surname of the person to which the document was issued.
surname	string	The data extracted from an MRZ field related to the surname of the person to which the document was issued.
address	object	The data extracted from the submitted document, specifically from fields that are related to the address of the person to whom the document was issued.
parsedAddress	object	A parsed version of the address of the person to whom the document was issued.
addressLine1	string	The data extracted from an MRZ field related to the first line of the address, as printed, of the person to which the document was issued.
addressLine2	string	The data extracted from an MRZ field related to the second line of the address, as printed, of the person to which the document was issued.
addressLine3	string	The data extracted from an MRZ field related to the third line of the address, as printed, of the person to which the document was issued.
addressLine4	string	The data extracted from an MRZ field related to the fourth line of the address, as printed, of the person to which the document was issued.
city	string	The parsed out city of the address of the person to whom the document was issued.
postalCode	string	The parsed out postal code of the address of the person to whom the document was issued.
stateOrProvince	string	The parsed out state or province of the address of the person to whom the document was issued.
unparsedAddress	object	An unparsed version of the address of the person to whom the document was issued.
addressLine1	string	The data extracted from an MRZ field related to the first line of the address, as printed, of the person to which the document was issued.
addressLine2	string	The data extracted from an MRZ field related to the second line of the address, as printed, of the person to which the document was issued.
addressLine3	string	The data extracted from an MRZ field related to the third line of the address, as printed, of the person to which the document was issued.
addressLine4	string	The data extracted from an MRZ field related to the fourth line of the address, as printed, of the person to which the document was issued.
faceComparisonInfo	object	Contains the result of Face Comparison
acceptance	object
result	string	Determination of whether the images provided were of sufficient quality to be processed Values: ACCEPTED REJECTED
reasons	string (array)	The reasons that the service is unable to complete face comparison. MISSING_SELFIE: One or more images are missing selfie for processing face comparison. Please retake live selfie image before resubmitting them. MISSING_PORTRAIT: One or more document images are missing portrait required for processing face comparison. Please retake document image containing portrait before resubmitting them. NOT_HUMAN_FACE: One or more document images have portrait without human face for processing face comparison. Please retake document image containing human face portrait before resubmitting them. PARTIALLY_VISIBLE_HUMAN_FACE: One or more of the submitted images could not be processed due to a human face that is only partially visible. Please retake the images containing the complete human face portrait before resubmitting them. PORTRAIT_IS_FAKE: One or more document images have a portrait with strong evidence of forgery and is thus not eligible for face comparison Please retake the live document image containing a real portrait before resubmitting them. SELFIE_NOT_LIVE: One or more selfies are deemed not live which is not eligible for face comparison. Please recapture the live selfie image before resubmitting them. OUT_OF_FOCUS: One or more of the submitted images could not be processed due to the image being out of focus. Please retake the images before resubmitting them. POOR_CONTRAST: One or more of the submitted images could not be processed due to the image having poor contrast. Please retake the images before resubmitting them. POOR_EXPOSURE: One or more of the submitted images could not be processed due to the image having poor exposure. Please retake the images before resubmitting them. GLARE: One or more of the submitted images could not be processed due to the image having glare on essential elements. Please retake the images before resubmitting them. FACE_TOO_CLOSE_SELFIE_IMAGE: The face in the selfie image is too close to the camera. FACE_TOO_FAR_SELFIE_IMAGE: The face in the selfie image is too far from the camera. FACE_ANGLE_TOO_LARGE_SELFIE_IMAGE: The angle between the face and camera is too large in the selfie image. QUALITY_TOO_LOW_SELFIE_IMAGE: The selfie has failed the image quality check. TOO_MANY_FACES_SELFIE_IMAGE: More than one face was detected in the selfie image.
findings	object	The following fields are related to the overall findings that resulted from the processing of the face comparison.
faceComparisonApproval	string	Service approval result containing manual comparison judgement . MATCH: The value will be returned in case selfie photo matches portrait image of document holder. NOT_MATCH: The value will be returned in case selfie photo does not match portrait image of document holder.
faceLivenessApproval	string	Service approval result containing automatic liveness judgement . LIVE: The value will be returned in case selfie photo is considered to be a live photo. NOT_LIVE: The value will be returned in case selfie photo is considered to be not a live photo.

ID Verification Result codes

Results list:

Status	Description
OK	The field TEST_GLOBAL_AUTHENTICITY_VALUE is OK. A message in warning field can exist.
NotCorrect:	The field TEST_GLOBAL_AUTHENTICITY_VALUE is FAIL
NotProcessed:	When server cannot return any information. Document could not be processed, for example when failing to recognize the document. A message in warning field can exist.
Warning.	Warning message. In this case it would have to analyze the other test fields of test to have more details of the warning. For example in the case of sending two not corresponding images the TEST_SIDE_CORRESPONDENCE would indicate FAIL

Service Operation Status

Status list:

Status	Description
Completed	Indicates that the operation was succesfully completed
Processing	Indicates that the operation still in process.
Error	Indicates that during the operation was an error

Other Documentation

• Country Codes

Errors Codes

Error Code	Description
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your token Authorization is wrong.
404	Not Found -- The specified resource could not be found.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.