POST /v1/search — Paginated Asset Declaration Search

The /v1/search endpoint is the primary way to retrieve asset declaration records from the PDN. Unlike /v1/summary, which fans out to multiple providers, this endpoint routes to exactly one provider identified by supplier_id and returns the full paginated record payload that provider returns. The gateway normalises your request through two middleware stages — createQuery and createOrder — that map flat input fields to the nested structure expected by upstream providers before forwarding the request.

Endpoint

POST /v1/search
Content-Type: application/json

Request Body

Required Fields

supplier_id

string

required

Identifies the target data provider. Must match a supplier_id value from GET /v1/providers. The request fails with HTTP 500 if this field is missing or does not match any configured provider.

Pagination Fields

page

number

Page number to retrieve. Defaults to 1 if omitted, null, or non-numeric.

pageSize

number

Number of records per page. Defaults to 10 if omitted, null, or non-numeric.

Query Filters

All filter fields are passed inside a query object. Omitting the query object (or passing an empty object) returns all records subject only to pagination.

query

object

An object containing one or more filter criteria. All fields are optional. Empty strings, null, and the string "0" are treated as absent.

Show query fields

string

Filter by the unique record ID assigned by the upstream provider.

nombres

string

Filter by the given names of the public servant.

primerApellido

string

Filter by the public servant’s first (paternal) surname.

segundoApellido

string

Filter by the public servant’s second (maternal) surname.

escolaridadNivel

string

Filter by the education level (escolaridadNivel) of the public servant.

formaAdquisicion

string

Filter by the method of acquisition of real estate assets. Internally mapped to bienesInmuebles.formaAdquisicion in the upstream query.

Employment fields — mapped internally to datosEmpleoCargoComision:

nombreEntePublico

string

Name of the public entity where the servant is employed.

entidadFederativa

string

Federal entity (state) of employment.

municipioAlcaldia

string

Municipality or borough of employment.

empleoCargoComision

string

Position or commission title held by the public servant.

nivelOrdenGobierno

string

Government order level of the employment (e.g., federal, state, municipal).

nivelEmpleoCargoComision

string

Employment or commission rank level.

Range fields — provide Min and/or Max suffixed variants for numeric range filtering. Internally mapped to bienesInmuebles.* except totalIngresosNetos:

superficieConstruccionMin

number

Minimum built surface area of real estate (square metres).

superficieConstruccionMax

number

Maximum built surface area of real estate (square metres).

superficieTerrenoMin

number

Minimum land surface area of real estate (square metres).

superficieTerrenoMax

number

Maximum land surface area of real estate (square metres).

valorAdquisicionMin

number

Minimum acquisition value of real estate assets.

valorAdquisicionMax

number

Maximum acquisition value of real estate assets.

totalIngresosNetosMin

number

Minimum total net income of the public servant. Mapped directly to totalIngresosNetos.min.

totalIngresosNetosMax

number

Maximum total net income of the public servant. Mapped directly to totalIngresosNetos.max.

Sort Options

sort

object

An object specifying sort direction for one or more fields. Use 1 for ascending and -1 for descending. Omitting this object returns results in the provider’s default order.

Show sort fields

Top-level sortable fields:

nombres

number

Sort by given names. 1 = ascending, -1 = descending.

primerApellido

number

Sort by first surname.

segundoApellido

number

Sort by second surname.

escolaridadNivel

number

Sort by education level.

totalIngresosNetos

number

Sort by total net income.

Employment sortable fields — mapped internally to datosEmpleoCargoComision:

nombreEntePublico

number

Sort by the name of the employing public entity.

entidadFederativa

number

Sort by federal entity (state).

municipioAlcaldia

number

Sort by municipality or borough.

empleoCargoComision

number

Sort by position or commission title.

nivelEmpleoCargoComision

number

Sort by employment rank level.

nivelOrdenGobierno

number

Sort by government order level.

Real estate sortable fields — mapped internally to bienesInmuebles:

superficieConstruccion

number

Sort by built surface area.

superficieTerreno

number

Sort by land surface area.

formaAdquisicion

number

Sort by method of acquisition.

valorAdquisicion

number

Sort by acquisition value.

Example Request

curl -X POST http://localhost:3101/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "supplier_id": "EDOMEX",
    "page": 1,
    "pageSize": 10,
    "query": {
      "nombres": "Juan",
      "primerApellido": "García"
    },
    "sort": {
      "primerApellido": 1
    }
  }'

Response

On success, the gateway returns HTTP 200 OK with the provider’s full response payload passed through. The response is enriched with supplier_id, supplier_name, levels, and endpoint_type by the upstream fetch layer.

Error Responses

Both error conditions below return HTTP 500. Ensure supplier_id is always provided and matches a value from GET /v1/providers before calling this endpoint.

Missing supplier_id:

HTTP 500

{
  "error": "Debe proporcionar un proveedor de información"
}

supplier_id not found in configured providers:

HTTP 500

{
  "error": "Proveedor de información no disponible"
}

Overview

Endpoints

Data Models

POST /v1/search — Paginated Asset Declaration Search

Endpoint

Request Body

Required Fields

Query Filters

Sort Options

Example Request

Response

Error Responses

Build docs developers (and LLMs) love

Overview

Endpoints

Data Models

Documentation Index

​Endpoint

​Request Body

​Required Fields

​Pagination Fields

​Query Filters

​Sort Options

​Example Request

​Response

​Error Responses

Build docs developers (and LLMs) love

Endpoint

Request Body

Required Fields

Pagination Fields

Query Filters

Sort Options

Example Request

Response

Error Responses