Search Person

Create Search

POST /risks/legal-records/searches

Runs an initial legal records query based on a person's first name and/or last names.

---

Required Headers (HTTP Headers)

Header	Type	Required	Value / Example
Content-Type	string	Yes	application/json

Authentication

Authenticate with the method Blacktrust defined for your integration: the x-api-key header or Authorization: Bearer {accessToken} (one or the other, never both). See Authentication to find out which one applies to you.

---

Query Params

Name	Type	Required	Default	Description
limit	string	No	100	Total records per page
page	string	No	1	Page to retrieve
categories	string	No	—	List of categories. Comma-separated list: Amparo,Penal
states	string	No	—	List of states. Comma-separated list: CDMX,Durango
clientId	string	Conditional	—	Client identifier. Required if the account has multiple clients assigned. Maximum 64 characters.

---

Search Body Examples

JSON

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

Property Reference

Parameter	Type	Required	Description
name	string	Yes	First name(s) of the person to search.
lastName	string	Conditional	Paternal last name of the person to search.
secondLastName	string	Conditional	Maternal last name of the person to search.

Name Criteria Rules

• You must provide name together with at least one of the two last names (lastName or secondLastName).

• Valid combinations are: name + lastName, name + secondLastName, or all three fields.

• Important: If you do not have one of the last names, omit the property from the JSON. Do not send empty strings ("").

---

API Responses

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 in Response

The UUID received in the response can later be used to check the status of the uploaded document and of each of the candidates it contained.

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 in Response

The UUID received in the response can later be used to check the status of the uploaded document and of each of the candidates it contained.

Field Types

Field	Type	Note
meta.searchId	string	Key for the other 3 endpoints
meta.outcome	enum	SUCCESS | EMPTY | FAILED
source.kpis.total_matches	number	Full universe. Feeds the charts
source.pagination.*	number	Pagination from the source: it does not know about the 300 cap
meta.pagination.*	number	Reachable, with the cap applied. This is the one that feeds the paginator
meta.cap.total_records_in_source	number	Actual total in the source
meta.cap.truncated	boolean	true → show "refine your search"
source.records[].uuid	string	Key for the detail and the CSV
source.records[].count	number	Number of lawsuits. Absent if the source does not report it
source.records[].categories	string[]	May be []
meta.unlocked_uuids	string[]	Unlocked uuids. Replaces records[].locked
meta.charged	boolean	Always true on this endpoint
meta.recoverable_until	string	ISO 8601
meta.slow_response	boolean	true if the source took longer than the threshold

---

Paginate or Retrieve Search

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

Gets additional pages of an existing search or applies secondary filters over the cached results without generating extra charges.

---

Path

Name	Type	Required	Description
searchId	string	Yes	Unique search identifier generated by the search service.

Query Params

Name	Type	Required	Default	Description
limit	string	No	100	Total records per page
page	string	No	1	Page to retrieve
categories	string	No	—	List of categories. Comma-separated list: Amparo,Penal
states	string	No	—	List of states. Comma-separated list: CDMX,Durango
clientId	string	Conditional	—	Client identifier. Required if the account has multiple clients assigned. Maximum 64 characters.

Filter Behavior

Applying or changing the categories or states parameters on this endpoint re-evaluates the in-memory data and does not generate any additional cost (charged: false).

It is recommended to reset the query to the first page (page=1) when changing filters.