API del RUI (Registro Universal de Ingresos) por documento

Qué problema resuelve

El RUI cambió el nombre y la lógica de la focalización social, pero mucha documentación —y mucha gente— sigue diciendo Sisbén. Quien integra necesita el grupo vigente y no quiere adivinar cuál de las dos escalas le están devolviendo. Esta API entrega las dos, identificadas, en una sola llamada, y con un candado que impide publicar una clasificación sobre alguien que no está registrado.

Para quién sirve

Operadores de programas sociales y subsidios, entidades territoriales, cajas de compensación, empresas de servicios públicos con tarifa diferencial, y plataformas que validan elegibilidad antes de otorgar un beneficio.

Datos requeridos

• docType — tipo de documento (CC, CE, TI, RC, PA, PPT o PEP).
• docNumber — número de documento.

Fuentes y cobertura

• Ventanilla Social del DNPGrupo, nivel y grupo de ingresos del Registro Universal de Ingresos; grupo y nivel del Sisbén IV; y los datos básicos de la persona con su municipio de residencia.

¿Qué es el RUI y en qué se diferencia del Sisbén?

El Registro Universal de Ingresos clasifica a la población por ingreso observado y estimado, y es el criterio que hoy usa la focalización del gasto social. El Sisbén IV clasifica por condiciones de vida en grupos A a D. Son escalas distintas y pueden no coincidir; esta API devuelve las dos para que quien decide elija cuál aplica.

¿Cómo consultar el grupo del RUI por cédula?

Con una llamada POST a /api/rui enviando docType y docNumber. La respuesta trae el grupo, el nivel y el grupo de ingresos del RUI, más el grupo del Sisbén y los datos básicos de la persona.

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/rui' \
  -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": "clasificacion-social",
  "status": "info",
  "data": {
    "documento": "1020304050",
    "persona": {
      "nombre": "JUAN CARLOS PEREZ GOMEZ",
      "sexo": "Masculino",
      "edad": 38
    },
    "ubicacion": {
      "departamento": "VALLE DEL CAUCA",
      "municipio": "CALI",
      "codigoMunicipio": "76001"
    },
    "rui": {
      "grupo": "C",
      "nivel": "C15",
      "grupoIngresos": "Ingreso observado y estimado"
    },
    "sisben": {
      "grupo": "B",
      "nivel": "B6",
      "descripcion": "Pobreza moderada"
    }
  }
}

Explicación campo por campo

Limitaciones y posibles errores

• El RUI y el Sisbén son escalas distintas y pueden no coincidir para la misma persona. La API devuelve las dos identificadas; cuál aplica lo define el programa que consulta, no nosotros.
• El servicio oficial del grupo Sisbén le asigna 'D4 – no pobre, no vulnerable' a documentos que NO existen. Está medido. Por eso la existencia la decide el registro de ingresos y el grupo del Sisbén solo se publica si esa verificación pasó.
• Una persona no registrada responde 404 y NO cobra.
• Es un registro de personas naturales: con NIT se responde 400 sin cobrar.
• Es el mismo dato que /api/sisben y comparte su caché: llamar a los dos no cuesta el doble, pero tampoco trae información distinta.

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 del RUAF: EPS, pensión y ARL→
• API de nombre por cédula→
• Documentación e integración→