Buscar Persona

Crear Búsqueda

POST /risks/legal-records/searches

Ejecuta una consulta inicial de antecedentes legales basada en el nombre y/o apellidos de una persona.

---

Encabezados Requeridos (HTTP Headers)

Header	Tipo	Requerido	Valor / Ejemplo
Content-Type	string	Sí	application/json

Autenticación

Autentícate con el método que Blacktrust definió para tu integración: el header x-api-key o Authorization: Bearer {accessToken} (uno u otro, nunca ambos). Consulta Autenticación para saber cuál aplica en tu caso.

---

Query Params

Nombre	Tipo	Requerido	Default	Descripción
limit	string	No	100	El total de registros por página
page	string	No	1	Página a consultar
categories	string	No	—	Lista de categorías. Lista separada por comas: Amparo,Penal
states	string	No	—	Lista de estados. Lista separada por comas: CDMX,Durango
clientId	string	Condicional	—	Identificador del cliente. Obligatorio si la cuenta tiene asignados múltiples clientes. Máximo 64 caracteres.

---

Ejemplos de Body de Búsqueda

JSON

{
  "name": "Armando",
  "lastName": "Perez",
  "secondLastName": "Gomez"
}

Relación de propiedades

Parámetro	Tipo	Requerido	Descripción
name	string	Sí	Nombre(s) de la persona a buscar.
lastName	string	Condicional	Apellido paterno de la persona a buscar.
secondLastName	string	Condicional	Apellido materno de la persona a buscar.

Reglas para Criterios de Nombre

• Debe proporcionar obligatoriamente name acompañado de al menos uno de los dos apellidos (lastName o secondLastName).

• Las combinaciones válidas son: name + lastName, name + secondLastName, o las tres casillas completas.

• Importante: Si no cuenta con alguno de los apellidos, omita la propiedad en el JSON. No envíe cadenas vacías ("").

---

Respuestas de la API

200 OK

{
  "isSuccess": true,
  "statusCode": 200,
  "message": "Búsqueda ejecutada",
  "data": {
    "searchId": "9f0c3b52-2f8f-4a2f-9a0e-7b1a0c3d4e5f",
    "outcome": "SUCCESS",
    "search_query": {
      "name": "AGUSTIN",
      "lastName": "TORRES",
      "secondLastName": "MUNGUIA",
      "full_name_searched": "AGUSTIN TORRES MUNGUIA"
    },
    "kpis": {
      "total_matches": 130,
      "top_categories": [{ "category": "Penal", "count": 139 }],
      "top_states": [{ "state": "Federal", "count": 10 }]
    },
    "records": [
      {
        "uuid": "e9f54242-c097-4696-a28e-837f1c892304",
        "name": "AGUSTIN TORRES MUNGUIA",
        "count": 49,
        "categories": ["LABORAL", "PENAL"],
        "agreement_date": "10-01-2026",
        "state": "CDMX"
      }
    ],
    "meta": {
      "searchId": "9f0c3b52-2f8f-4a2f-9a0e-7b1a0c3d4e5f",
      "outcome": "SUCCESS",
      "cap": {
        "max_matches": 300,
        "total_records_in_source": 2137,
        "truncated": true
      },
      "pagination": {
        "total_records_found": 300,
        "current_page": 1,
        "limit": 10,
        "total_pages": 30,
        "has_next": true,
        "has_previous": false
      },
      "unlocked_uuids": [],
      "charged": true,
      "recoverable_until": "2026-08-19T14:00:00.000Z",
      "slow_response": false
    }
  }
}

UUID En Respuesta

El UUID recibido en la respuesta podrá ser usado posteriormente para consultar el estatus del documento cargado y cada uno de los candidatos que se encontraban en el.

200 No Content

{
  "searchId": "…",
  "outcome": "EMPTY",
  "search_query": { "…": "…" },
  "kpis": { "total_matches": 0, "top_categories": [], "top_states": [] },
  "pagination": {
    "total_records_found": 0,
    "current_page": 1,
    "limit": 10,
    "total_pages": 0,
    "has_next": false,
    "has_previous": false
  },
  "cap": {
    "max_matches": 300,
    "total_records_in_source": 0,
    "truncated": false
  },
  "records": [],
  "charged": true,
  "recoverable_until": "2026-08-19T14:00:00.000Z",
  "slow_response": false
}

UUID En Respuesta

El UUID recibido en la respuesta podrá ser usado posteriormente para consultar el estatus del documento cargado y cada uno de los candidatos que se encontraban en el.

Tipos de los campos

Campo	Tipo	Nota
meta.searchId	string	Llave para los otros 3 endpoints
meta.outcome	enum	SUCCESS | EMPTY | FAILED
source.kpis.total_matches	number	Universo completo. Alimenta las gráficas
source.pagination.*	number	La paginación de la fuente: no conoce el tope de 300
meta.pagination.*	number	Alcanzable, con el tope aplicado. Es la que alimenta el paginador
meta.cap.total_records_in_source	number	Total real de la fuente
meta.cap.truncated	boolean	true → mostrar "refina tu búsqueda"
source.records[].uuid	string	Llave del detalle y del CSV
source.records[].count	number	Número de juicios. Ausente si la fuente no lo informa
source.records[].categories	string[]	Puede venir []
meta.unlocked_uuids	string[]	uuid desbloqueados. Reemplaza a records[].locked
meta.charged	boolean	Siempre true en este endpoint
meta.recoverable_until	string	ISO 8601
meta.slow_response	boolean	true si la fuente tardó más del umbral

---

Paginar o Recuperar Búsqueda

GET /risks/legal-records/searches/{searchId}

Obtiene las páginas adicionales de una búsqueda existente o aplica filtros secundarios sobre los resultados almacenados en caché sin generar cargos extra.

---

Path

Nombre	Tipo	Requerido	Descripción
searchId	string	Si	Identificador único de la búsqueda generado en el servicio de búsqueda.

Query Params

Nombre	Tipo	Requerido	Default	Descripción
limit	string	No	100	El total de registros por página
page	string	No	1	Página a consultar
categories	string	No	—	Lista de categorías. Lista separada por comas: Amparo,Penal
states	string	No	—	Lista de estados. Lista separada por comas: CDMX,Durango
clientId	string	Condicional	—	Identificador del cliente. Obligatorio si la cuenta tiene asignados múltiples clientes. Máximo 64 caracteres.

Comportamiento del Filtro

Aplicar o cambiar los parámetros categories o states en este endpoint re-evalúa la información en memoria y no genera ningún costo adicional (charged: false).

Se recomienda reiniciar la consulta a la página (page=1) al cambiar de filtros.