Biometric recognition for ID validation - Colombia

Lets integrate Biometric recognition for ID validation - Colombia in your system. First, get your Apitude API key, then send a POST request to Apitude... And that's it!.


import requests
url = "https://apitude.co/api/v1.0/requests/document-id-pe/"
payload = {'emotion': 'neutral', 'back_img': 'https://apitude.co/example/not/real/url/cedula_reverso.jpg', 'front_img': 'https://apitude.co/example/not/real/url/cedula_frente.jpg', 'selfie_img': 'https://apitude.co/example/not/real/url/cedula_selfie_neutral.jpg'}
headers = {
    'x-api-key': 'API-KEY',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())


OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
String payload = "{\"emotion\": \"neutral\", \"selfie_img\": \"https://apitude.co/example/not/real/url/cedula_selfie_neutral.jpg\", \"front_img\": \"https://apitude.co/example/not/real/url/cedula_frente.jpg\", \"back_img\": \"https://apitude.co/example/not/real/url/cedula_reverso.jpg\"}"
RequestBody body = RequestBody.create(mediaType, payload);
Request request = new Request.Builder()
  .url("https://apitude.co/api/v1.0/requests/document-id-pe/")
  .method("POST", body)
  .addHeader("x-api-key", "API-KEY")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();


var myHeaders = new Headers();
myHeaders.append("x-api-key", "API-KEY");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({"emotion": "neutral", "selfie_img": "https://apitude.co/example/not/real/url/cedula_selfie_neutral.jpg", "front_img": "https://apitude.co/example/not/real/url/cedula_frente.jpg", "back_img": "https://apitude.co/example/not/real/url/cedula_reverso.jpg"});
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};
fetch("https://apitude.co/api/v1.0/requests/document-id-pe/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));


url := "https://apitude.co/api/v1.0/requests/document-id-pe/"
method := "POST"
data := "{\"emotion\": \"neutral\", \"selfie_img\": \"https://apitude.co/example/not/real/url/cedula_selfie_neutral.jpg\", \"front_img\": \"https://apitude.co/example/not/real/url/cedula_frente.jpg\", \"back_img\": \"https://apitude.co/example/not/real/url/cedula_reverso.jpg\"}"
payload := strings.NewReader(data)
client := &http.Client {}
req, err := http.NewRequest(method, url, payload)
if err != nil {
    fmt.Println(err)
}
req.Header.Add("x-api-key", "API-KEY")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
fmt.Println(string(body))

Alternatively, the service also receives the following payload

In this case, instead of URLs, you could also send the images in the payload encoded as base64 strings


import requests
url = "https://apitude.co/api/v1.0/requests/document-id-pe/"
payload = {'emotion': 'neutral', 'back_img': '/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=', 'front_img': '/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=', 'selfie_img': '/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k='}
headers = {
    'x-api-key': 'API-KEY',
    'Content-Type': 'application/json'
}
response = requests.post(url, headers=headers, data=payload)
print(response.json())


OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
String payload = "{\"emotion\": \"neutral\", \"selfie_img\": \"/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=\", \"front_img\": \"/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=\", \"back_img\": \"/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=\"}"
RequestBody body = RequestBody.create(mediaType, payload);
Request request = new Request.Builder()
  .url("https://apitude.co/api/v1.0/requests/document-id-pe/")
  .method("POST", body)
  .addHeader("x-api-key", "API-KEY")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();


var myHeaders = new Headers();
myHeaders.append("x-api-key", "API-KEY");
myHeaders.append("Content-Type", "application/json");
var raw = JSON.stringify({"emotion": "neutral", "selfie_img": "/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=", "front_img": "/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=", "back_img": "/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k="});
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};
fetch("https://apitude.co/api/v1.0/requests/document-id-pe/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));


url := "https://apitude.co/api/v1.0/requests/document-id-pe/"
method := "POST"
data := "{\"emotion\": \"neutral\", \"selfie_img\": \"/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=\", \"front_img\": \"/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=\", \"back_img\": \"/9j/4AAQSkZJR...YOUR IMAGE ENCODEDIN BASE64...H/9k=\"}"
payload := strings.NewReader(data)
client := &http.Client {}
req, err := http.NewRequest(method, url, payload)
if err != nil {
    fmt.Println(err)
}
req.Header.Add("x-api-key", "API-KEY")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
fmt.Println(string(body))

That POST request should return the following


{
    "message": "Request processed successfully",
    "url": "/api/v1.0/requests/document-id-pe/e0606c19-a32d-410f-b2eb-d57a665677bc/",
    "request_id": "e0606c19-a32d-410f-b2eb-d57a665677bc"
}

This response will contains a unique request ID that you should poll using a GET as follows


import requests
url = "https://apitude.co/api/v1.0/requests/document-id-pe/e0606c19-a32d-410f-b2eb-d57a665677bc/"
headers = {
    'x-api-key': 'API-KEY',
    'Content-Type': 'application/json'
}
response = requests.get(url, headers=headers)
print(response.json())


OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
Request request = new Request.Builder()
  .url("https://apitude.co/api/v1.0/requests/document-id-pe/e0606c19-a32d-410f-b2eb-d57a665677bc/")
  .method("GET")
  .addHeader("x-api-key", "API-KEY")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();


var myHeaders = new Headers();
myHeaders.append("x-api-key", "API-KEY");
myHeaders.append("Content-Type", "application/json");
var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};
fetch("https://apitude.co/api/v1.0/requests/document-id-pe/e0606c19-a32d-410f-b2eb-d57a665677bc/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));


url := "https://apitude.co/api/v1.0/requests/document-id-pe/e0606c19-a32d-410f-b2eb-d57a665677bc/"
method := "GET"
client := &http.Client {}
req, err := http.NewRequest(method, url)
if err != nil {
    fmt.Println(err)
}
req.Header.Add("x-api-key", "API-KEY")
req.Header.Add("Content-Type", "application/json")
res, err := client.Do(req)
defer res.Body.Close()
body, err := ioutil.ReadAll(res.Body)
fmt.Println(string(body))

How does the response looks like?


{
   "result": {
      "data": {
         "face_id": true,
         "back_info": {
            "birthday": "1972-03-22",
            "date_expedition": "1990-08-15",
            "document_number": "888888881"
         },
         "face_match": true,
         "front_info": {
            "gender": "male",
            "emotion": {
               "fear": 0.0,
               "anger": 0.0,
               "disgust": 0.0,
               "neutral": 0.933,
               "sadness": 0.066,
               "contempt": 0.0,
               "surprise": 0.0,
               "happiness": 0.0
            },
            "process_id": "33d77916-c6e1-46b5-90b5-b349a244906c",
            "face_rectangle": {
               "top": 334,
               "left": 656,
               "right": 825,
               "width": 169,
               "bottom": 503,
               "height": 169
            },
            "document_number": "888888881"
         },
         "selfie_info": {
            "gender": "female",
            "emotion": {
               "fear": 0.0,
               "anger": 0.0,
               "disgust": 0.0,
               "neutral": 0.861,
               "sadness": 0.022,
               "contempt": 0.002,
               "surprise": 0.0,
               "happiness": 0.114
            },
            "process_id": "399b5bcc-58f9-4700-8304-d5446dd09746",
            "face_rectangle": {
               "top": 115,
               "left": 98,
               "right": 273,
               "width": 175,
               "bottom": 290,
               "height": 175
            }
         },
         "registraduria": {
            "area": "BOLIVAR",
            "city": "CARTAGENA",
            "name": "JUAN PEREZ",
            "status": "VIGENTE",
            "resolution": "",
            "date_resolution": "2020-05-30"
         },
         "liveness_check": true,
         "face_match_score": 0.84552,
         "national_registry": true
      },
      "error": "",
      "end_at": "2020-11-01 06:46:37.602006",
      "status": 200,
      "message": "successful",
      "queried_by": "YOUR-USER",
      "service_name": "face-id-co"
   },
   "message": "Request completed"
}

Ok, but what does each field in that JSON means?

The general parts:

message:The message is an Apitude generated string with an informational text about the request.
result:The result is contains the main part of the request.
result.error:The error is a string generated by apitude for the request if everything worked it will be blank.
result.message:The message is a string with two options successful or unsuccessful depending of how your request finished.
result.queried_by:The queried_by field is a string that lets you know what user started the request.
result.end_at:The end_at field is a string formatted date that lets you know at what time the request ended in Apitude.
result.service_name:The service_name field is a string that echos the service called. For this service it will always be document-id-pe.
result.status:The status field is a integer that represents whether the service returned data from the input sent in the request. It could be one of the following values:
- 200: The service returned response data for the payload that was sent in the creation of the request.
- 404: The service did not returned data for the payload that was sent in the creation of the request.
- 400: The service did not started because your input was invalid.
- 500: Apitude tried to execute your request, however the service Apitude uses to execute your request was down. Please wait some time and try again, Apitude will not charged you for requests with this code.
Depending on the service, you want it to return different codes. For example, if you are checking the user against a security list to whitelist the user you should look for a 404, because a 200 would mean the user is in fact in the list. Other cases however, like creating objects in the name of a user you want the code to be 200, since it will imply the creation was a success.

The data in the response:

data.selfie_info:This field is a dictionary with the biometrical information of the submited selfie image.
data.back_info:This field is a dictionary with the OCR information of the rear face (barcode) of the submited Colombian national ID image.
data.front_info:This field is a dictionary with the OCR information of the frontal face of the submited Colombian national ID image.
data.face_match:This field is a boolean with the matching between the selfie face image and the face in the frontal image of the Colombian national ID. A value of true would mean both are the same person, a value of false would mean otherwise.
data.registraduria:This field is a dictionary with the information of the submited Colombian national ID in the database of the National Registry of Civil Status of Colombia.
data.liveness_check:This field is a boolean with the matching between the selfie face image and the submited emotion. A value of true would mean the face in the selfie is performing the emotion submited as a parameter, a value of false would mean otherwise.
data.face_match_score:This field is a decimal number with a value between 0.0 and 1.0. A value of 1.0 means the face in the selfie and the face in the face in the frontal image of the Colombian national ID are identical.
data.national_registry:This field is a boolean with a value of true if the Colombian national ID was validated by the National Registry of Civil Status of Colombia.
data.face_id:This field is a boolean with a value of true if the fields data.face_match, data.national_registry and data.liveness_check are all true, a value of false would mean otherwise.

About this service

The service allows a person to validate through API. It receives as input an emotion, a selfie photo of the user performing the selected emotion (The possible values are surprise, sadness, neutrality, anger and happiness), a photo of the front of the Colombian ID (side of the image and name) and a later photo of the Colombian ID (barcode side) and obtain the following validations:

The image with the selfie contains the face of only one person.
The face of the person in the selfie corresponds to the sentiment.
The face of the person in the selfie and the face on the ID are of the same person.
The cedula is active in the National Registry of Civil Status of Colombia

The service returns in its response:

If the selfie image is valid or not
If the selfie image and the front face of the ID are from the same person
If the person in the selfie is performing the sentiment
If the ID is active and valid in the National Registry of Civil Status of Colombia or not
The information on the front side of the ID
The information on the back side of the ID
The identification information in the registry