NAV Navbar
http

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

{
    "service": "KYC API",
    "status": "ok",
    "date": "2020-03-02 15:47:58 +00:00"
}

503 Service Unavailable

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

Returned Fields

Parameter Type Description
service string Name of the API Service. (Always return "KYC API")
status string Status of the API. For HTTP 200: always return "ok".
date string Date and time of the request (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)

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, KYT generates POST request with data to user endpoint.

Requests may be generated from following IP addresses: 217.75.233.139 , 213.134.38.77 , 88.26.209.16 .

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

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.