API de EPS en Colombia: afiliación en salud por documento
PlacApi consulta la Base de Datos Única de Afiliados (BDUA) de la ADRES y devuelve en JSON la afiliación en salud de una persona: la EPS, el régimen (contributivo o subsidiado), el estado (activo o retirado), el tipo de afiliado (cotizante, beneficiario, cabeza de familia) y las fechas de afiliación y finalización, junto con sus datos básicos y su ciudad. afiliaciones trae el historial completo —una fila por traslado de EPS o cambio de régimen— y la fila ACTIVA es la afiliación vigente. No pide la fecha de expedición del documento y responde en segundos.
¿No eres desarrollador? Consulta el RUNT por placa aquí sin escribir código.
Qué problema resuelve
Saber si una persona está afiliada, a qué EPS y en qué régimen es la pregunta de una vinculación laboral, un estudio de seguridad o una verificación de referencias. La consulta oficial de la ADRES exige pasar por un formulario con captcha y leer una ventana emergente, así que no sirve dentro de un flujo automatizado. Este endpoint hace ese recorrido y entrega el dato ya estructurado en segundos.
Para quién sirve
Áreas de talento humano que verifican afiliación antes de contratar, empresas de estudios de seguridad, entidades de crédito que confirman actividad laboral, plataformas de contratación de personal, y cualquier sistema que necesite responder «¿qué EPS tiene hoy esta persona?» por API.
Datos requeridos
- docType — tipo de documento (CC, TI, CE, PA, RC, NU, AS, MS, CD, CN, SC, PE, PT o PC). Por defecto CC.
- docNumber — número de documento: de 1 a 14 dígitos, o de 8 a 10 caracteres alfanuméricos si es pasaporte o permiso. No se pide fecha de expedición.
Fuentes y cobertura
- ADRES — Base de Datos Única de Afiliados (BDUA)Registro oficial de afiliación al sistema de salud: EPS, régimen, estado, tipo de afiliado y fechas, tal como lo reportan las EPS a la ADRES.
¿Cómo consultar la EPS de una persona por cédula desde una API?
Con una llamada POST a /api/eps enviando docType y docNumber. La respuesta trae la EPS, el régimen, el estado y el tipo de afiliado, con el historial completo de afiliación y los datos básicos de la persona.
¿Por qué hay filas repetidas en afiliaciones?
Cada traslado de EPS o cambio de régimen agrega una fila al historial. La fila con estado ACTIVO es la afiliación vigente; las anteriores documentan por dónde pasó la persona.
Ejemplo de solicitud
POST https://placapi.com/api/eps. Autenticación por API key en el header x-api-key. Los datos del ejemplo son ficticios.
curl -X POST 'https://placapi.com/api/eps' \
-H 'x-api-key: pk_live_TU_CLAVE' \
-H 'content-type: application/json' \
-d '{"docType":"CC","docNumber":"1020304050"}'Ejemplo de respuesta
Respuesta JSON (fragmento con los campos de esta consulta; la API integral devuelve todas las fuentes en el mismo objeto).
{
"source": "afiliacion-salud-adres",
"status": "info",
"data": {
"documento": "1020304050",
"tipoDocumento": "CC",
"persona": {
"nombres": "JUAN CARLOS",
"apellidos": "PEREZ GOMEZ",
"fechaNacimiento": null,
"departamento": "VALLE",
"municipio": "SANTIAGO DE CALI"
},
"afiliaciones": [
{
"estado": "ACTIVO",
"entidad": "NUEVA EPS S.A.",
"regimen": "CONTRIBUTIVO",
"fechaAfiliacion": "01/09/2018",
"fechaFinalizacion": null,
"tipoAfiliado": "COTIZANTE"
}
],
"fechaImpresion": "09/07/2026 12:26:07"
}
}Explicación campo por campo
| Campo | Tipo | Descripción |
|---|---|---|
| afiliaciones | array | Historial completo de afiliación. La fila con estado ACTIVO es la afiliación vigente; una persona con traslados trae varias. |
| afiliaciones[].entidad | string | La EPS, tal como la escribe el registro. |
| afiliaciones[].regimen | string | CONTRIBUTIVO o SUBSIDIADO. |
| afiliaciones[].estado | string | ACTIVO, RETIRADO, SUSPENDIDO… según lo reportado por la EPS. |
| afiliaciones[].fechaFinalizacion | string|null | null = afiliación vigente, sin fecha de fin (la fuente escribe 31/12/2999 como centinela). |
| persona.fechaNacimiento | string|null | La fuente la enmascara (**/**/**), por eso llega null. No es un hueco de esta API: el portal tampoco la muestra. |
Tiempo de respuesta
Alrededor de 3 segundos: tres peticiones contra un formulario estatal, sin captcha que resolver.
Precio y cobro
1 crédito por consulta con datos, desde 349 COP. El precio por crédito baja por volumen: 349 COP desde 30, 249 COP desde 1.000, 149 COP desde 5.000, 139 COP desde 10.000, 119 COP desde 20.000, 99 COP desde 50.000. Los créditos se compran por adelantado (mínimo 30 = 10.470 COP), no vencen y no hay mensualidad. El mismo precio aplica por la web y por API. Solo se cobra cuando la consulta devuelve datos; por API, las consultas sin resultado (404) tienen 10 gratis al mes por cada tipo de respuesta sin datos y después cobran igual.
Caché y actualización
3 días con datos, 1 hora sin ellos. La afiliación a EPS es de lo que más rápido se mueve en el sistema de seguridad social y se cachea corto a propósito.
Seguridad y privacidad
La placa y el documento se usan solo para ejecutar la consulta; el resultado queda en caché temporal. No se almacenan datos de tarjetas (los pagos los procesa Wompi). Ver privacidad y seguridad.
Limitaciones y posibles errores
- La fuente enmascara la fecha de nacimiento: llega null siempre, aunque la persona exista.
- Una persona que no está en BDUA responde 404 y NO cobra. «No está afiliado en salud» no es lo mismo que «sin afiliación»: el registro refleja lo reportado por las EPS con su propio rezago.
- Es un registro de personas naturales: con NIT se responde 400 sin cobrar.
- Es la misma sección salud de /api/ruaf, que además exige la fecha de expedición del documento. Esta es la versión puntual: misma EPS, menos campos, menos espera y menos costo.
- El estado de la afiliación es el que reportó la EPS; las novedades pueden tardar días en reflejarse.
Códigos de error del endpoint (401, 402, 429, 5xx) en la referencia de errores.
Otras preguntas frecuentes
¿Qué diferencia hay con /api/ruaf?
+
La sección salud del RUAF es este mismo dato, pero el RUAF exige la fecha de expedición del documento, cuesta 2 créditos y tarda decenas de segundos generando un informe completo de seguridad social. /api/eps responde solo la pregunta de la EPS, en segundos y por 1 crédito.
¿Qué pasa si la persona no está en BDUA?
+
Se responde 404 y no se cobra. Es la respuesta honesta del registro: la ADRES refleja lo que las EPS le reportan, con su propio rezago, así que un 404 dice «no registra afiliación», no necesariamente «nunca ha estado afiliada».
¿La fecha de nacimiento sale enmascarada?
+
Sí, la enmascara la propia fuente (//**) y por eso el campo llega null. El portal público tampoco la muestra.
Seguir explorando
Última revisión: 7 de septiembre de 2026 · Versión de la API: v1 · Fuentes y metodología