API del Sisbén en Colombia: grupo, nivel y clasificación por documento

Qué problema resuelve

Los programas sociales, los subsidios y varias tarifas diferenciales dependen del grupo del Sisbén, y verificarlo obliga a entrar al portal del DNP persona por persona. Además, la consulta con clave del ciudadano exige un segundo factor, así que no sirve para un flujo automatizado. Este endpoint entrega la clasificación por API y agrega el candado de calidad que la fuente no trae.

Para quién sirve

Operadores de programas sociales y subsidios, cajas de compensación, empresas de servicios públicos con tarifa diferencial, entidades territoriales, 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 y nivel del Sisbén IV, grupo del Registro Universal de Ingresos, y los datos básicos de la persona con su municipio de residencia.

¿Cómo consultar el grupo del Sisbén por cédula desde una API?

Con una llamada POST a /api/sisben enviando docType y docNumber. La respuesta trae el grupo y el nivel del Sisbén IV, el grupo del RUI y los datos básicos de la persona con su municipio.

¿Qué diferencia hay entre el grupo del Sisbén y el del RUI?

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

Ejemplo de solicitud

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

curl -X POST 'https://placapi.com/api/sisben' \
  -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"
    },
    "sisben": {
      "grupo": "B",
      "nivel": "B6",
      "descripcion": "Pobreza moderada"
    },
    "rui": {
      "grupo": "C",
      "nivel": "C15",
      "grupoIngresos": "Ingreso observado y estimado"
    }
  }
}

Explicación campo por campo

Limitaciones y posibles errores

• El endpoint oficial del grupo Sisbén le asigna 'D4 – no pobre, no vulnerable' a documentos que NO existen. Está medido. Por eso la existencia de la persona la decide el registro de ingresos y el grupo solo se publica si esa verificación pasó: un sisben en null significa 'existe pero sin grupo publicado', jamás un dato fabricado.
• Una persona no registrada responde 404 y NO cobra.
• Es un registro de personas naturales: con NIT se responde 400 sin cobrar.
• El grupo se actualiza en recertificaciones y barridos del DNP, no en tiempo real.

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

Otras preguntas frecuentes

Seguir explorando

• API del RUAF: EPS, pensión y ARL→
• API de nombre por cédula→
• API de bienes y rentas→
• Documentación e integración→
• API del RUI: registro de ingresos→
• API de puesto de votación por cédula→