API del RUAF: afiliaciones a seguridad social por cédula

Qué problema resuelve

Saber si una persona está cotizando hoy, a qué EPS y por qué régimen es la pregunta de una vinculación laboral, un estudio de seguridad o una verificación de referencias. Consultarlo oficialmente exige pasar por un portal con captcha y esperar a que un visor de reportes genere el informe. Este endpoint hace ese recorrido y entrega las siete secciones ya estructuradas, en vez de siete consultas separadas a siete entidades.

Para quién sirve

Áreas de talento humano que verifican afiliación antes de contratar, empresas de estudios de seguridad, operadores de riesgos laborales, entidades de crédito que confirman actividad laboral, y plataformas de contratación de personal.

Datos requeridos

• docType — tipo de documento. Por defecto CC.
• docNumber — número de documento.
• fechaExpedicion — fecha de expedición del documento en formato DD/MM/AAAA. La exige la fuente para autenticar, no nosotros.

Fuentes y cobertura

• RUAF — Registro Único de Afiliados, Ministerio de Salud y Protección SocialInforme de afiliaciones de una persona: salud, pensiones, riesgos laborales, compensación familiar, cesantías, pensionados y vinculación a programas de asistencia social, con la fecha de corte del propio informe.

¿Cómo saber a qué EPS está afiliada una persona desde una API?

Con una llamada POST a /api/ruaf enviando docNumber y fechaExpedicion. El bloque salud trae la EPS, el régimen (contributivo o subsidiado), el tipo de afiliado, el estado de la afiliación y el municipio.

¿Por qué se necesita la fecha de expedición del documento?

Porque la fuente del Ministerio la exige para autenticar la consulta. No es un requisito nuestro: sin ese dato el portal no responde. Va en formato DD/MM/AAAA.

Ejemplo de solicitud

POST https://placapi.com/api/ruaf. Autenticación por API key en el header x-api-key. Los datos del ejemplo son ficticios.

curl -X POST 'https://placapi.com/api/ruaf' \
  -H 'x-api-key: pk_live_TU_CLAVE' \
  -H 'content-type: application/json' \
  -d '{"docType":"CC","docNumber":"1020304050","fechaExpedicion":"05/10/2018"}'

Ejemplo de respuesta

Respuesta JSON (fragmento con los campos de esta consulta; la API integral devuelve todas las fuentes en el mismo objeto).

{
  "source": "afiliaciones-seguridad-social",
  "status": "info",
  "data": {
    "fechaCorte": "2026-08-14",
    "persona": {
      "nombre": "MARIA FERNANDA GOMEZ RUIZ",
      "sexo": "F"
    },
    "salud": {
      "tiene": true,
      "registros": [
        {
          "administradora": "NUEVA EPS S.A.",
          "regimen": "Contributivo",
          "fechaAfiliacion": "01/11/2024",
          "estado": "Activo",
          "tipoAfiliado": "COTIZANTE",
          "ubicacion": "SANTIAGO DE CALI"
        }
      ]
    },
    "pensiones": {
      "tiene": true,
      "registros": []
    },
    "riesgosLaborales": {
      "tiene": true,
      "registros": []
    },
    "compensacionFamiliar": {
      "tiene": true,
      "registros": []
    },
    "cesantias": {
      "tiene": true,
      "registros": []
    },
    "pensionado": {
      "tiene": false,
      "registros": []
    },
    "asistenciaSocial": {
      "tiene": true,
      "registros": []
    }
  }
}

Explicación campo por campo

Limitaciones y posibles errores

• Requiere la fecha de expedición del documento en DD/MM/AAAA. Sin ella la fuente no responde, y una fecha que no coincide devuelve 404 sin cobrar: es un dato mal escrito, no un veredicto sobre la persona.
• No se acepta el formato AAAA-MM-DD: la fuente lo leería al revés y respondería 'no coincide' sin explicar por qué.
• La fecha de corte del informe va con rezago frente a la realidad. Una afiliación de esta semana puede no aparecer todavía.
• Es un registro de personas naturales: con NIT se responde 400 sin cobrar.
• Cuesta 2 créditos, el doble que el resto de la familia, porque es el scrape más caro del catálogo. A cambio sustituye siete consultas.

Códigos de error del endpoint (401, 402, 429, 5xx) en la referencia de errores.

Otras preguntas frecuentes

Seguir explorando

• API del Sisbén: grupo y clasificación→
• API de nombre por cédula→
• API de antecedentes judiciales→
• API de bienes y rentas→
• Documentación e integración→
• API del RUI: registro de ingresos→