Integrating Colombia and Peru Biometric Services using Apitude

Overview

The Colombia and Peru Biometric services offer comprehensive solutions for identity verification and document authenticity checks. They combine advanced facial recognition technology with optical character recognition (OCR) to provide robust verification processes for Colombian and Peruvian identification documents.

Key Features

• Facial recognition and matching
• Document OCR and data extraction
• Support for multiple document types and versions
• Integration with national registries for additional verification (Colombia)
• Verification of both blue and electronic (white) Peruvian ID cards
• Extraction of UBIGEO codes for precise location information (Peru)

Integration Process

1. Capture or upload a selfie of the user
2. Capture or upload the front of the identification document
3. Capture or upload the back of the identification document
4. Process the images and receive verification results

Technical Implementation

Both services are implemented as RESTful APIs, allowing easy integration with various platforms and programming languages. The main endpoints are:

Colombia

• POST https://apitude.co/api/v1.0/biometric/face-id-co/ - Create a new verification request
• PATCH https://apitude.co/api/v1.0/biometric/face-id-co/<check_id>/front/ - Upload and process the front of the document
• PATCH https://apitude.co/api/v1.0/biometric/face-id-co/<check_id>/back/ - Upload and process the back of the document
• GET https://apitude.co/api/v1.0/biometric/face-id-co/<check_id>/ - Retrieve the verification results

Peru

• POST https://apitude.co/api/v1.0/biometric/face-id-pe/ - Create a new verification request
• PATCH https://apitude.co/api/v1.0/biometric/face-id-pe/<check_id>/front/ - Upload and process the front of the document
• PATCH https://apitude.co/api/v1.0/biometric/face-id-pe/<check_id>/back/ - Upload and process the back of the document
• GET https://apitude.co/api/v1.0/biometric/face-id-pe/<check_id>/ - Retrieve the verification results

Country-Specific Features

Colombia

• Integration with national registries for additional verification
• Support for various Colombian identification document versions

Peru

• Automatic detection of blue (older) or electronic (white) ID card types
• Extraction and validation of UBIGEO codes for precise location information
• Support for both DNI (Documento Nacional de Identidad) and Carnet de Extranjería
• Handling of Peruvian naming conventions (given name, middle name, first last name, second last name)

Integration Examples

Code Examples

Creating a Biometric Verification Request

import requests
import json

url = "https://apitude.co/api/v1.0/requests/biometric/"
payload = {
    "country": "CO",  # Use "PE" for Peru
    "document_type": "CC",  # Cédula de Ciudadanía for Colombia, use "DNI" for Peru
    "document_number": "1234567890",
    "birth_date": "1990-01-01"
}
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())
      

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://apitude.co/api/v1.0/requests/biometric/"
    payload := map[string]string{
        "country":         "CO",  // Use "PE" for Peru
        "document_type":   "CC",  // Cédula de Ciudadanía for Colombia, use "DNI" for Peru
        "document_number": "1234567890",
        "birth_date":      "1990-01-01",
    }

    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("x-api-key", "YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
      

import okhttp3.*;
import org.json.JSONObject;

public class BiometricRequest {
    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient().newBuilder().build();
        MediaType mediaType = MediaType.parse("application/json");

        JSONObject payload = new JSONObject();
        payload.put("country", "CO");  // Use "PE" for Peru
        payload.put("document_type", "CC");  // Cédula de Ciudadanía for Colombia, use "DNI" for Peru
        payload.put("document_number", "1234567890");
        payload.put("birth_date", "1990-01-01");

        RequestBody body = RequestBody.create(mediaType, payload.toString());
        Request request = new Request.Builder()
            .url("https://apitude.co/api/v1.0/requests/biometric/")
            .method("POST", body)
            .addHeader("x-api-key", "YOUR_API_KEY")
            .addHeader("Content-Type", "application/json")
            .build();
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}
      

const fetch = require('node-fetch');

const url = 'https://apitude.co/api/v1.0/requests/biometric/';
const payload = {
    country: 'CO',  // Use 'PE' for Peru
    document_type: 'CC',  // Cédula de Ciudadanía for Colombia, use 'DNI' for Peru
    document_number: '1234567890',
    birth_date: '1990-01-01'
};

const options = {
    method: 'POST',
    headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
};

fetch(url, options)
    .then(res => res.json())
    .then(json => console.log(json))
    .catch(err => console.error('error:' + err));
      

Retrieving Biometric Verification Results

import requests

url = "https://apitude.co/api/v1.0/requests/biometric/e0606c19-a32d-410f-b2eb-d57a665677bc/"
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(url, headers=headers)
print(response.json())
      

package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
)

func main() {
    url := "https://apitude.co/api/v1.0/requests/biometric/e0606c19-a32d-410f-b2eb-d57a665677bc/"
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("x-api-key", "YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}
      

import okhttp3.*;

public class BiometricResult {
    public static void main(String[] args) throws Exception {
        OkHttpClient client = new OkHttpClient().newBuilder().build();
        Request request = new Request.Builder()
            .url("https://apitude.co/api/v1.0/requests/biometric/e0606c19-a32d-410f-b2eb-d57a665677bc/")
            .method("GET", null)
            .addHeader("x-api-key", "YOUR_API_KEY")
            .addHeader("Content-Type", "application/json")
            .build();
        Response response = client.newCall(request).execute();
        System.out.println(response.body().string());
    }
}
      

const fetch = require('node-fetch');

const url = 'https://apitude.co/api/v1.0/requests/biometric/e0606c19-a32d-410f-b2eb-d57a665677bc/';

const options = {
    method: 'GET',
    headers: {
        'x-api-key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
};

fetch(url, options)
    .then(res => res.json())
    .then(json => console.log(json))
    .catch(err => console.error('error:' + err));
      

Response Format

After making a request to the biometric service, you will receive a response in the following format:

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

You should use the provided request_id to poll for the results of your biometric verification request.

Interpreting Results

The result of your biometric verification will contain the following key information:

• result.status: An integer representing the outcome of the verification:
  • 200: Successful verification
  • 404: No data found for the provided input
  • 400: Invalid input
  • 500: Service error (you will not be charged for these requests)
• result.face_match: A boolean indicating whether the selfie matches the document photo
• result.face_match_score: A float representing the confidence of the face match
• result.liveness_check: A boolean indicating whether the selfie passed the liveness check
• result.extracted_data: An object containing the extracted information from the document

Security Considerations

To ensure the security and privacy of user data:

• All API requests must be authenticated using API keys
• Data is encrypted in transit using TLS
• Biometric data is processed and discarded, not stored long-term
• Compliance with Colombian and Peruvian data protection regulations
• Never expose your API key in client-side code
• Use HTTPS for all API calls
• Implement rate limiting to prevent abuse
• Store sensitive information securely and in compliance with local data protection laws

Best Practices for Integration

Image Quality

Ensure that the images you submit (both selfies and document scans) are of high quality:

• Use well-lit environments for capturing images
• Ensure the entire document is visible and not cut off
• Avoid glare or reflections on the document
• For selfies, ensure the face is clearly visible and not obstructed

Error Handling

Implement robust error handling in your integration:

• Check for and handle HTTP error codes appropriately
• Implement retries with exponential backoff for transient errors
• Provide clear error messages to your users when verification fails

Performance

Optimize your integration for performance:

• Implement asynchronous processing for better user experience
• Use webhooks (if available) for real-time updates instead of polling
• Implement caching where appropriate to reduce API calls

User Experience

Enhance the user experience in your application:

• Provide clear instructions for users when capturing selfies and document images
• Implement a progress indicator during the verification process
• Offer guidance and support for users who fail verification

Testing

Thoroughly test your integration:

• Use test credentials and sample images provided by Apitude
• Test various scenarios, including successful verifications and different types of failures
• Implement end-to-end testing in your CI/CD pipeline

Want to start using this service?