Query AucoFace process

GET /veriface HTTP/1.1
HOST: {{api_auco}}
Authorization: {{public_key}}

Service to query the status and results of a previously created AucoFace process.

Authentication

Include your public key in the Authorization header.

Authorization: puk_xxx...

Query parameters

Name	Description
code String	Required. AucoFace process code to query. This code is obtained when creating the process via the /veriface endpoint.

Response structure

The response contains AucoFace process information organized in different sections:

Main process fields

Field	Type	Description
email	String	Email of the process creator
createdAt	String	Process creation date in Date JSON format
platform	String	Platform used: whatsapp, web
status	String	Current process status see process statuses
emailValidated	String	Email of who approved or rejected the manual validation
name	String	Full name of the person to validate
userEmail	String	Email of the person to validate
phone	String	Phone number of the person to validate with country code
country	String	Country of the person to validate. Check list of documents and countries
identificationType	String	Type of document of the person to validate. Check list of documents and countries
identificationNumber	String	Identity document number of the person to validate
ocrData	Object	Data extracted from document via OCR. See OCR Data for some data that can be obtained.
attempts	Array	List of validation attempts performed
custom	Object	Additional information added during process creation

Process statuses

Status	Description
INPROGRESS	Process in progress, user is performing validation
BLOCKED	User exceeded maximum attempts, requires manual validation on the platform
APPROVED	Validation completed successfully, documents and biometrics are valid
INVALIDATED	Process completed, but validation was not successful
EXPIRED	Process expired without completing within time limit

Attempt information (Array attempts)

Each attempt may contain all or part of the following information:

Field	Description
identificationCardFront	Temporary URL of the front document image
identificationCardBack	Temporary URL of the back document image
photo	Temporary URL of the face photograph
similarity	Biometric similarity percentage (0-100)
identificationCardData	Data extracted from document via OCR
date	Timestamp of the attempt
successfull	Boolean indicating if the attempt was successful
errorMessages	Array of errors in case of failure

OCR Data (ocrData)

Information extracted from the identity document:

• Personal data: fullName, givenNames, surname, documentNumber
• Demographic information: dateOfBirth, sex, bloodGroup, height
• Document data: documentType, firstIssueDate, placeOfIssue
• Location: issuingStateName, placeOfBirth

Temporary URLs

Image URLs (identificationCardFront, identificationCardBack, photo) are temporary AWS S3 links with a validity of 5 minutes. After this time, it will be necessary to perform a new query to get updated URLs.

Data availability

• The ocrData field is available only when it was possible to extract information from the document
• The attempts array may contain multiple attempts if the user performed several validations
• OCR data may vary according to document type, country and image quality

🧪 Usage examples

Curl

curl -X GET '{{api_auco}}/veriface?code=VERIFACE_CODE' \
  -H 'Authorization: {{public_key}}'

Python

import requests

response = requests.get(
  '{{api_auco}}/veriface',
  params={'code': 'VERIFACE_CODE'},
  headers={'Authorization': '{{public_key}}'}
)
print(response.json())

Node.js

const axios = require('axios');

axios.get('{{api_auco}}/veriface', {
  params: { code: 'VERIFACE_CODE' },
  headers: { Authorization: '{{public_key}}' }
})
.then((response) => console.log(response.data));

📥 Example responses

Approved process.

{
  "email": "prueba@auco.ai",
  "createdAt": "2025-05-29T14:53:04.074Z",
  "platform": "whatsapp",
  "status": "APPROVED",
  "name": "Juan Pérez",
  "userEmail": "juan.perez@gmail.com",
  "phone": "+573003003030",
  "country": "CO",
  "identificationType": "CC",
  "identificationNumber": "1001001010",
  "attempts": [
    {
      "identificationCardFront": "https://amazon.url/file/signed-url",
      "identificationCardBack": "https://amazon.url/file/signed-url",
      "photo": "https://amazon.url/file/signed-url",
      "similarity": 91.31532287597656,
      "identificationCardData": {
        "documentNumber": "1001001010",
        "fullName": "PÉREZ JUAN",
        "givenNames": "JUAN",
        "issuingStateName": "Colombia",
        "surname": "PÉREZ",
        "documentType": "Id Card",
        "name": "JUAN PÉREZ"
      },
      "date": "2025-05-29T17:16:51.839Z",
      "successfull": true
    }
  ],
  "ocrData": {
    "bloodGroup": "O+",
    "dateOfBirth": "1990-05-15",
    "firstIssueDate": "2015-03-20",
    "height": "175 cm",
    "issuingStateName": "Colombia",
    "placeOfBirth": "BOGOTÁ (CUNDINAMARCA)",
    "sex": "M",
    "documentType": "Id Card",
    "placeOfIssue": "BOGOTÁ",
    "documentNumber": "1001001010",
    "fullName": "PÉREZ JUAN",
    "givenNames": "JUAN",
    "surname": "PÉREZ",
    "name": "JUAN PÉREZ"
  }
}

Process in progress.

{
  "email": "prueba@auco.ai",
  "createdAt": "2025-05-29T14:53:04.074Z",
  "platform": "whatsapp",
  "status": "INPROGRESS",
  "name": "Juan Pérez",
  "userEmail": "juan.perez@gmail.com",
  "phone": "+573003003030",
  "country": "CO",
  "identificationType": "CC",
  "identificationNumber": "1001001010",
  "attempts": []
}

Blocked process.

{
  "email": "prueba@auco.ai",
  "createdAt": "2025-05-29T14:53:04.074Z",
  "platform": "whatsapp",
  "status": "BLOCKED",
  "emailValidated": "supervisor@auco.ai",
  "name": "Juan Pérez",
  "phone": "+573003003030",
  "country": "CO",
  "identificationType": "CC",
  "identificationNumber": "1001001010",
  "attempts": [
    {
      "identificationCardFront": "https://amazon.url/file/signed-url",
      "photo": "https://amazon.url/file/signed-url",
      "similarity": 45.23456789,
      "identificationCardData": {
        "documentNumber": "1001001010",
        "fullName": "PÉREZ JUAN",
        "documentType": "Id Card"
      },
      "date": "2025-05-29T17:15:31.383Z",
      "errorMessages": [
        {
          "key": "ID_BACK",
          "error": "error_identification_not_document"
        }
      ],
      "successfull": false
    }
  ]
}

Invalidated process.

{
  "email": "prueba@auco.ai",
  "createdAt": "2025-05-29T14:53:04.074Z",
  "platform": "web",
  "status": "INVALIDATED",
  "name": "Juan Pérez",
  "phone": "+573003003030",
  "country": "CO",
  "identificationType": "CC",
  "identificationNumber": "1001001010",
  "attempts": [
    {
      "identificationCardFront": "https://amazon.url/file/signed-url",
      "photo": "https://amazon.url/file/signed-url",
      "similarity": 32.15432167891234,
      "date": "2025-05-29T17:15:31.383Z",
      "successfull": false
    }
  ]
}

⚠️ Error Responses

Code	Description
400	Invalid or malformed process code.
401	Invalid or missing authentication.