Query

GET /validate/background HTTP/1.1
HOST: {{api_auco}}
Authorization: {{public_key}}

Service to query a background check validation.

Authentication

Include your public key in the Authorization header.

Authorization: puk_xxx...

Query Parameters

Name	Description
code String	Required. Process code to query.

🧪 Usage examples

Curl

curl -X GET '{{api_auco}}/validate/background' \
  -H 'Authorization: {{public_key}}'
  --data-urlencode 'code=XXXXXXXXX'

Python

import requests

response = requests.get(
  "{{api_auco}}/validate/background",
  headers={"Authorization": "{{public_key}}"},
  params={"code": "XXXXXXXXX"}
)
print(response.json())

Node.js

const axios = require('axios');

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

📥 Example responses

info

The ready property indicates whether the validation process has been completed or if the document is not yet ready. If the document is ready, the url property will be provided with the signed URL for downloading the document. Signed URLs are valid for 2 minutes before they expire.

Pending validation.

{
  "code": "XXXXXXXXX",
  "name": "1001001010",
  "email": "example@auco.ai",
  "data": {
    "name": "FIRSTNAME LASTNAME LASTNAME",
    "type": "CC",
    "identification": "1001001010",
    "expeditionDate": "01/01/1995"
  },
  "ready": false
}

Ready validation.

{
  "code": "XXXXXXXXX",
  "name": "1001001010",
  "url": "https://s3.amazonaws.com/.../signed-url",
  "email": "example@auco.ai",
  "data": {
    "type": "CC",
    "identification": "1001001010",
    "expeditionDate": "01/01/1995",
    "name": "FIRSTNAME LASTNAME LASTNAME",
    "error": true,
    "reports": false
  },
  "ready": true,
  "validation": {
    "contaduria": false,
    "contraloria": false,
    "defuncion": {
      "date": "25/02/2026",
      "doc": 1001001010,
      "validity": "Vigente (Vivo)"
    },
    "delitos_sexuales": [],
    "hallazgos": {
      "altos": [],
      "bajos": [
        {
          "cantidad": "001",
          "codigo": "sigep",
          "coincidencia": "True",
          "descripcion": "The queried document has its resume with employment information and background registered in Colombia's Public Employment Information and Management System (SIGEP).",
          "fuente": "sigep",
          "hallazgo": "SIGEP: The queried document is registered in the Public Employment Information and Management System",
          "html_id": null
        },
        {
          "cantidad": "001",
          "codigo": "reputacional_news",
          "coincidencia": "True",
          "descripcion": "The document holder may appear in at least one news article or website when searched by their full name.",
          "fuente": "reputacional",
          "hallazgo": "Reputational News: The queried name appears in at least one news article or website.",
          "html_id": null
        },
        {
          "cantidad": "001",
          "codigo": "reputacional_social",
          "coincidencia": "True",
          "descripcion": "The document holder may appear on a social network such as Facebook, LinkedIn, YouTube, or Twitter.",
          "fuente": "reputacional",
          "hallazgo": "Social Networks: The queried name shows a match on a social network",
          "html_id": null
        }
      ],
      "infos": [
        {
          "cantidad": "001",
          "codigo": "rut",
          "coincidencia": "True",
          "descripcion": "The document holder is registered in the Unified Tax Registry (RUT).",
          "fuente": "rut",
          "hallazgo": "RUT: The queried document is found in the Unified Tax Registry.",
          "html_id": null
        },
        {
          "cantidad": "001",
          "codigo": "rama_proceso_csv",
          "coincidencia": "True",
          "descripcion": "The name, when queried in the source, appears in more than one judicial process.",
          "fuente": "rama_unificada",
          "hallazgo": "Unified Branch: The queried name appears in 15 processes with partial match.",
          "html_id": "https://app.auco.ai/validation/download/rama_unificada/example-uuid.zip"
        }
      ],
      "medios": []
    },
    "nivel": "bajo",
    "interpol": false,
    "ofac": false,
    "policia": false,
    "proveedores_ficticios": false,
    "rama": {
      "bogotajepms": false,
      "medellinjepms": false,
      "calijepms": false,
      "barranquillajepms": false
    },
    "rama_unificada": [
      {
        "actuaciones": [],
        "cantFilas": 0,
        "claseProceso": "",
        "demandado": null,
        "demandante": null,
        "departamento": "",
        "despacho": "",
        "detalle": false,
        "dict_data_extra": [
          {
            "number_of_pages": 1,
            "number_of_private_records": 0,
            "number_of_records": 15,
            "pages_consulted": 1,
            "processes_active": 0,
            "registra_como_hallazgo": true,
            "url_csv": "https://app.auco.ai/validation/download/rama_unificada/example-uuid.zip"
          }
        ],
        "esPrivado": null,
        "fechaConsulta": "2026-02-25T14:52:03",
        "fechaProceso": "",
        "idProceso": 0,
        "llaveProceso": "",
        "tipoProceso": "",
        "ubicacion": ""
      }
    ],
    "registraduria": {
      "cedula": "1001001010",
      "estado": "VIGENTE",
      "fecha_exp": "1 DE ENERO DE 1995",
      "lugar_exp": "BOGOTA - CUNDINAMARCA",
      "nombre": "FIRSTNAME LASTNAME LASTNAME"
    },
    "rues": {
      "actividades_economicas": [
        "4721 Comercio al por menor de productos agrícolas para el consumo en establecimientos especializados"
      ],
      "categoria_matricula": "PERSONA NATURAL",
      "clase_identificacion": "CEDULA DE CIUDADANIA",
      "estado": "ACTIVA",
      "identificacion": "NIT 1001001010",
      "matricula": "0000000000",
      "municipio": "BOGOTA / CUNDINAMARCA",
      "nit": 1001001010,
      "organizacion_juridica": "PERSONA NATURAL",
      "razon_social": "LASTNAME FIRSTNAME",
      "registro_mercantil": {
        "categoria_de_la_matricula": "PERSONA NATURAL",
        "estado_de_la_matricula": "ACTIVA",
        "fecha_de_matricula": "2026-01-01",
        "fecha_de_renovacion": "2026-01-01",
        "numero_de_matricula": "000000",
        "tipo_de_organización": "PERSONA NATURAL",
        "tipo_de_sociedad": "SOCIEDAD COMERCIAL",
        "último_año_renovado": "2026"
      },
      "tipo": "SOCIEDAD COMERCIAL"
    },
    "rut": "1001001010-0",
    "rut_estado": "REGISTRO ACTIVO"
  }
}

---

Response fields

Field	Type	Description
code	String	Unique code of the validation process.
name	String	Queried identification number.
email	String	Email address associated with the process.
url	String	Signed URL to download the PDF report. Only present when ready: true. Expires in 2 minutes.
ready	Boolean	Indicates whether the validation has been completed.
data	Object	Basic data of the queried person.
data.name	String	Full name of the person.
data.type	String	Document type (e.g., CC, CE, PA).
data.identification	String	Identification number.
data.expeditionDate	String	Document expedition date.
data.error	Boolean	Indicates if there was an error in any query source.
data.reports	Boolean	Indicates if negative reports were found.
validation	Object	Detailed background check validation results. Only present when ready: true.

validation object fields

Field	Type	Description
contaduria	Boolean	Result from the General Accounting Office (Contaduría General de la Nación) query.
contraloria	Boolean	Result from the Comptroller General (Contraloría General de la República) query.
defuncion	Object	Death status information. Includes date, doc, and validity.
delitos_sexuales	Array	Records found in the sexual offenses database.
hallazgos	Object	Findings classified by risk level.
hallazgos.altos	Array	High-risk findings.
hallazgos.medios	Array	Medium-risk findings.
hallazgos.bajos	Array	Low-risk findings.
hallazgos.infos	Array	Informational findings.
nivel	String	Overall risk level: bajo (low), medio (medium), or alto (high).
interpol	Boolean	Result from Interpol watchlist query.
ofac	Boolean	Result from OFAC sanctions list query.
policia	Boolean	Result from police background check query.
proveedores_ficticios	Boolean	Result from DIAN fictitious suppliers list query.
rama	Object	Results from judicial office (JEPMS) queries by city. Each key is a boolean.
rama_unificada	Array	Unified Judicial Branch judicial process results.
registraduria	Object	National Registry (Registraduría Nacional) information. Includes cedula, estado, fecha_exp, lugar_exp, and nombre.
rues	Object	Unified Business and Social Registry (RUES) information.
rut	String	Unified Tax Registry (RUT) number.
rut_estado	String	RUT status (e.g., REGISTRO ACTIVO).

Finding structure

Each element in hallazgos.altos, hallazgos.medios, hallazgos.bajos, and hallazgos.infos has the following structure:

Field	Type	Description
cantidad	String	Number of matches found.
codigo	String	Identifier code of the finding type.
coincidencia	String	Indicates if there was a match ("True" / "False").
descripcion	String	Detailed description of the finding.
fuente	String	Information source.
hallazgo	String	Summary of the finding.
html_id	String | null	URL to download the finding detail, if applicable.

⚠️ Error Responses

Code	Description
400	Missing parameters code. Process not found VALIDATION_NOT_FOUND.
401	Invalid or missing authentication.