API para empresas

Documentación de la API de personas políticamente expuestas

La API de Entitymx es una API REST de una sola operación, POST /v1/match enhttps://n2.entitymx.com, que recibe un nombre y, de forma opcional, fecha de nacimiento, entidad, CURP o RFC. Responde de inmediato, de forma síncrona y sin webhook, con hasta 50 candidatos de personas que ocupan u ocuparon un cargo público en México, cada uno con su porcentaje de coincidencia, sus razones, los factores que conviene verificar y su evidencia.

Autenticación

Cada petición lleva tu llave en la cabecera Authorization: Bearer <tu llave> y una clave distinta por búsqueda en la cabecera Idempotency-Key, que es obligatoria. Sin ella la respuesta es 400 missing_idempotency_key.

La llave se genera en tu página de API, después de crear tu cuentay pagar la suscripción mensual, que es lo que deja la API abierta. Al generarla eliges su vigencia: 30, 90, 180 o 365 días. La llave se muestra una sola vez, así que guárdala en ese momento. Si la pierdes, generas otra y la anterior deja de funcionar en ese instante, igual que una llave revocada (401 revoked_api_key) o vencida (401 expired_api_key).

La petición

El cuerpo es JSON. El nombre y el primer apellido son obligatorios: o bien full_name, o biengiven_names y paternal_surname. Un campo que no está en esta tabla responde 400unknown_parameter.

Campo	Tipo	Obligatorio	Descripción
`full_name`	texto	Sí, si no envías las partes	Nombre completo. Al menos dos palabras comparables. Máximo 300 caracteres.
`given_names`	texto	Sí, si no envías full_name	Nombres de pila. Va junto con paternal_surname.
`paternal_surname`	texto	Sí, si no envías full_name	Primer apellido. Tiene que coincidir con el del registro para que aparezca: igual, con la misma pronunciación o con una letra de diferencia (desde 5 letras).
`maternal_surname`	texto	No	Segundo apellido.
`birth_date`	fecha AAAA-MM-DD	No	Fecha de nacimiento. Si falta, cuenta la fecha que trae la CURP o el RFC. Cada cuenta compara como máximo 3 fechas distintas contra una misma persona en 30 días; desde la cuarta, la fecha ya no se compara para esa persona y la respuesta lo avisa en meta.warnings.
`birth_year`	entero	No	Año de nacimiento. Si envías también birth_date, deben coincidir.
`state`	texto	No	Clave de la entidad, de 01 a 32.
`curp`	texto de 18 caracteres	No	CURP. Envía curp o rfc, nunca los dos (responde 400 conflicting_parameters).
`rfc`	texto de 13 caracteres	No	RFC de persona física. Envía rfc o curp, nunca los dos.
`match_threshold`	número de 60 a 100	No	Umbral de coincidencia del nombre. Por defecto 60. Un valor menor de 60 responde 400 invalid_parameter.
`page_size`	entero de 1 a 50	No	Máximo de candidatos del grupo partial por respuesta. Por defecto 50. Los que no caben se declaran en candidates_omitted. El grupo high no se corta por page_size.

De la CURP y del RFC solo se comparan los 10 primeros caracteres: las 4 siglas del nombre y la fecha de nacimiento (AAMMDD). El sexo, la entidad de nacimiento y la homoclave no se leen. La CURP y el RFC que envías no se guardan: solo se usan durante la consulta, y en la bitácora queda el nombre del campo, no su valor.

Ejemplo

La persona de este ejemplo es ficticia. Sustituye emx_live_TU_LLAVE por tu llave y usa una clave de petición distinta en cada búsqueda.

curl -X POST https://n2.entitymx.com/v1/match \
  -H "Authorization: Bearer emx_live_TU_LLAVE" \
  -H "Idempotency-Key: UNA_CLAVE_DISTINTA_POR_BUSQUEDA" \
  -H "Content-Type: application/json" \
  -d '{"given_names":"Ana","paternal_surname":"Ejemplo","maternal_surname":"Prueba","birth_date":"1980-01-01","state":"09","page_size":10,"match_threshold":70}'

El cuerpo de la petición, con sangría:

{
  "given_names": "Ana",
  "paternal_surname": "Ejemplo",
  "maternal_surname": "Prueba",
  "birth_date": "1980-01-01",
  "state": "09",
  "page_size": 10,
  "match_threshold": 70
}

La respuesta

La respuesta es un JSON con la lista de candidatos y, junto a ella, todo lo que se recortó o se dejó fuera, para que ninguna lista parezca completa sin serlo.

Campo	Qué es
`data`	Lista de candidatos, descrita abajo.
`meta`	request_id de la petición, algorithm_version, data_snapshot_id, processing_ms y warnings, la lista de avisos del motor sobre la consulta. algorithm_version y data_snapshot_id dicen con qué versión y con qué datos se respondió.
`truncation_applied`	true si la lista se recortó por el umbral o por el límite de página. Un recorte siempre se declara.
`candidates_omitted`	Cuántos candidatos dejaron fuera el umbral y el límite de página.
`high_group_omitted`	Solo aparece cuando es mayor que 0: cuántos candidatos del grupo high quedaron fuera porque el grupo pasó de 500.
`candidates_excluded_by_surname`	Cuántos registros pasaban el umbral por parecido de nombre y se dejaron fuera porque ni su primer apellido ni, en otro orden, su segundo apellido coinciden con el consultado. Se declara y no se esconde.
`groups`	Cuántos candidatos de data hay en cada grupo. high: el primer apellido coincide y la similitud del nombre es de 85 o más. partial: todo lo demás que aparece. La suma es el largo de data.
`groups_total`	Los mismos grupos sobre todo el conjunto, antes del límite de página. Solo viaja cuando difiere de groups.
`suggest_birth_date_or_id`	true cuando hay más de una coincidencia alta y la consulta no trae fecha de nacimiento ni CURP o RFC. Es una invitación a enviar uno de los dos, que es lo que separa a los homónimos.

Cada candidato

Campo	Qué es
`person_id`	Identificador del registro.
`full_name`	El nombre como lo publica la fuente, para que lo compares con tu expediente.
`score`	Porcentaje de coincidencia, de 0 a 99, que suma tres campos: nombre hasta 55, fecha de nacimiento hasta 30 y CURP o RFC hasta 14. Es coincidencia de datos, no probabilidad de identidad ni nivel de riesgo. Lo que la consulta no trae, o la fuente no publica, aporta 0.
`score_components`	Los puntos que aportó cada campo (nombre, fecha_nacimiento, curp_rfc).
`score_component_percent`	Cuánto coincidió cada campo en porcentaje de su propio peso, de 0 a 99, para mostrar una barra por campo.
`name_similarity`	Similitud del nombre, de 0 a 100. Es la que se compara con match_threshold.
`match_group`	high o partial. Agrupa y no decide.
`score_basis`	Qué campos entraron al cálculo. Un porcentaje sobre el nombre solo no vale lo mismo que uno con fecha de nacimiento.
`decision`	Una recomendación de tratamiento: match, possible_match o no_match. match significa que conviene tratarlo como coincidencia probable y verificarlo. Nunca es una afirmación de identidad: la identidad la resuelve tu empresa con su expediente.
`match_reasons`	Por qué apareció: campo, tipo de coincidencia y contribución.
`discriminating_factors`	Los datos que descartarían la coincidencia si los verificas contra tu expediente.
`verification_checks`	Las mismas verificaciones como semáforo: supports, unverified o contradicts, con su papel (reason o discriminator) y un resumen. Hablan de identidad y no de riesgo.
`pep_tier`	Nivel del cargo según la clasificación de Entitymx.
`pep_status`	current, former_within_regulatory_window o former. Un cargo sin fecha de término documentada se mantiene como current. Es nulo cuando el registro no es un cargo con nivel.
`current_appointments`	Los cargos del registro, con institución, nivel de gobierno, fechas y la confianza de cada fecha (documented, inferred o unknown).
`evidence`	El documento oficial que respalda el registro: tipo, identificador de la fuente, fecha de publicación (nula si la fuente no la publica), fecha de captura, sha256 del contenido y una escala de autoridad con su base.
`elected_unconfirmed, extended_category, review_required`	Banderas que aparecen solo cuando aplican, cada una con su nota o motivo. Indican que quien consulta debe verificar con más cuidado.

Ejemplo de respuesta con un candidato ficticio. El cargo, la institución y la fuente son inventados, y los valores de algorithm_version y data_snapshot_id son de ejemplo:

{
  "meta": {
    "request_id": "req_EJEMPLO0001",
    "algorithm_version": "ejemplo",
    "data_snapshot_id": "ejemplo",
    "processing_ms": 120,
    "warnings": []
  },
  "data": [
    {
      "person_id": "EMX-P-0000000000000000",
      "full_name": "ANA EJEMPLO PRUEBA",
      "score": 52,
      "score_components": {
        "nombre": 52,
        "fecha_nacimiento": 0,
        "curp_rfc": 0
      },
      "score_component_percent": {
        "nombre": 94,
        "fecha_nacimiento": 0,
        "curp_rfc": 0
      },
      "name_similarity": 94,
      "match_group": "high",
      "score_basis": [
        "nombre",
        "primer_apellido"
      ],
      "decision": "possible_match",
      "match_reasons": [
        {
          "field": "nombre",
          "match_type": "exact",
          "contribution": 52
        },
        {
          "field": "primer_apellido",
          "match_type": "exact",
          "contribution": 0
        }
      ],
      "discriminating_factors": [
        "La fuente no publica la fecha de nacimiento: verifícala contra tu expediente."
      ],
      "verification_checks": [
        {
          "check": "fecha_nacimiento",
          "role": "discriminator",
          "status": "unverified",
          "summary": "La fuente no publica la fecha de nacimiento, solo tu expediente puede descartar o confirmar."
        }
      ],
      "pep_tier": 3,
      "pep_status": "current",
      "current_appointments": [
        {
          "appointment_id": "apt_EJEMPLO0001",
          "position_title": "Presidencia municipal",
          "institution_name": "Ayuntamiento de un municipio de ejemplo",
          "government_level": "municipal",
          "pep_tier": 3,
          "start_date": null,
          "end_date": null,
          "tenure_start_confidence": "unknown",
          "tenure_end_confidence": "unknown",
          "is_current": true
        }
      ],
      "evidence": [
        {
          "evidence_id": "evi_EJEMPLO0001",
          "document_type": "periódico oficial estatal (ejemplo)",
          "source_id": "FUENTE-EJEMPLO",
          "published_at": null,
          "retrieved_at": "2026-10-01",
          "content_sha256": "0000000000000000000000000000000000000000000000000000000000000000",
          "authority_score": null,
          "authority_basis": "Ejemplo: la clase de la fuente no está declarada."
        }
      ]
    }
  ],
  "truncation_applied": false,
  "candidates_omitted": 0,
  "candidates_excluded_by_surname": 0,
  "groups": {
    "high": 1,
    "partial": 0
  },
  "suggest_birth_date_or_id": false
}

Cabeceras de respuesta, errores y límites

Cabecera	Qué dice
`X-Entitymx-Saldo`	Búsquedas que le quedan a la cuenta después de esta consulta.
`X-Entitymx-Cobrado`	Vale true cuando esta petición usó una búsqueda del saldo.
`Retry-After`	Solo en las respuestas 429: los segundos que debes esperar antes de reintentar.

Los errores traen un cuerpo JSON con error.type, error.code, error.message y request_id.

Código	Códigos de error	Qué significa y si cobra
400	`missing_idempotency_key, missing_required_field, invalid_parameter, unknown_parameter, conflicting_parameters`	Petición mal formada. Cobra una búsqueda si la cuenta tiene saldo (X-Entitymx-Cobrado: true); sin saldo sigue siendo 400 y no cobra. Nunca trae candidatos.
401	`missing_api_key, invalid_api_key, revoked_api_key, expired_api_key`	Llave ausente, inválida, revocada o vencida. No cobra.
402	`insufficient_tokens, subscription_required`	La cuenta no tiene búsquedas disponibles, o no tiene una suscripción activa. No entrega candidatos y no cobra. X-Entitymx-Saldo dice cuánto hay.
403	`wrong_port, api_operation_not_allowed, api_key_without_account, api_not_authorized`	La llave no tiene permiso para lo que pides. No cobra.
409	`algorithm_version_unavailable, snapshot_not_loaded`	La versión del algoritmo o la instantánea pedidas no son las cargadas. No cobra.
429	`rate_limited, too_many_failed_attempts`	Superaste el límite de ritmo, o hubo diez intentos sin llave válida desde la misma dirección en un minuto. Trae Retry-After. No cobra.
503	`billing_unavailable, billing_paused, audit_log_unavailable`	No se pudo cobrar o registrar la búsqueda, y sin eso no se entrega. No cobra.

El límite es de 5 búsquedas por segundo por cuenta, sumando las del sitio y las de la API, con una ráfaga de hasta 10. Al excederlo recibes 429 con Retry-After, y esa respuesta no se cobra.

Constancia de la búsqueda

Con la cabecera Accept: application/pdf la respuesta es la constancia de la búsqueda en PDF, en lugar del JSON. Lleva adjunta la respuesta exacta como respuesta.json, su sha256 impreso, que es el mismo que guarda la bitácora, y el nombre de la persona titular y el de la empresa que la cuenta capturó en Mi cuenta. Sin esos dos datos la respuesta es 422 constancia_data_missing y no se cobra. Se pide en la misma consulta y no tiene cargo adicional: se cobra como la búsqueda que la produce. Pedirla después, repitiendo la clave de petición, es otra búsqueda y cuesta una. Entitymx no conserva la constancia.

Para comprobar una constancia, se extrae respuesta.json del PDF y se calcula su sha256: tiene que ser el impreso. Accept: text/html sigue entregando la versión en HTML.

Qué se cobra

La API tiene una suscripción de $6,500.00 mxn al mes con IVA incluido. Además, cada consulta usa una búsqueda de tu saldo, a $6.00 mxn con IVA incluido. El detalle está enprecios.

Cada consulta se cobra según lo que responde el servicio:

Una consulta que el servicio ejecuta, traiga candidatos o no.
Una consulta repetida, aunque use la misma llave de petición.
Una consulta mal formada que el servicio rechaza.

Y no se cobra:

Una consulta sin llave válida o sin permiso.
Una consulta sin saldo.
Una consulta rechazada por exceder el límite de ritmo.
Una consulta que falla por un error del servicio.
La constancia, si se pide en la misma consulta.

Qué hace y qué no hace

La API tiene una sola operación, POST /v1/match. Cada consulta es una persona.
La API entrega candidatos con su evidencia. La decisión sobre si se trata de la misma persona, y qué hacer con ella, es de tu empresa.
Entitymx es una herramienta propia de consulta y es distinta de la lista oficial de la UIF y de la Consulta PEP 2.0.
El campo decision es una recomendación de tratamiento para verificar, y la identidad la resuelve quien consulta.
El monitoreo continuo y el envío de personas por lote son operaciones que la API para empresas no ofrece.
De las listas de sanciones internacionales, la API incluye solo a las personas físicas de las listas SDN y consolidada de OFAC, que se entregan como sanción internacional y nunca como PEP. La lista de la ONU y las demás listas internacionales no están incluidas.

Las fuentes que se consultan, con su estado medido y sus huecos declarados, están encobertura. Para conocer el servicio completo, visitala API para empresas, y para obtener el acceso,crea tu cuenta y genera tu llave en tu página de API.