API de licencias de conducción: verifica a tus conductores por cédula

Qué problema resuelve

Validar la licencia de un conductor —para vincularlo a una flota, una app de movilidad o un seguro— exige consultar el RUNT ciudadano, que resuelve por captcha y no ofrece API pública. PlacApi lo entrega como un endpoint REST por documento, con la respuesta ya normalizada en JSON.

Para quién sirve

Empresas de transporte y flotas que exigen licencia vigente antes de asignar un vehículo, apps de movilidad y última milla que verifican conductores, aseguradoras, rentadoras de vehículos, y escuelas de conducción y gestores de trámites que confirman cuándo quedó expedida una licencia y en qué categoría.

Datos requeridos

• docType — tipo de documento de la persona (CC, CE…).
• docNumber — número de documento de la persona. No se requiere placa.
• primerApellido — opcional: primer apellido del titular. Con él la consulta cuesta 1 crédito; sin él cuesta 2, porque lo averiguamos a partir del documento.

Fuentes y cobertura

• RUNT ciudadanoLicencias de conducción por persona: categoría, vigencias, estado del conductor, multas asociadas y paz y salvo. Consultado por cédula, sin placa.

¿Cómo consultar por API el estado de una licencia de conducción?

Con una llamada POST a /api/licencia de PlacApi que lleve docType, docNumber y, si lo tienes, primerApellido. La respuesta trae driverStatus, el estado del conductor en el RUNT, y el arreglo licenses con una entrada por categoría: category, status, licenceNumber, otExpide, expeditionDate, dueDate y restrictions, más resolutionNumber, startDateSuspension y endDateSuspension cuando hay una medida sobre la licencia. Para decidir si alguien puede manejar un vehículo hoy se busca en licenses la categoría de ese vehículo y se miran su status y su dueDate: una licencia vigente de moto no habilita para conducir un camión.

En producción responde con una mediana de 6,1 segundos y un percentil 90 de 8,9 segundos, medidos entre el 15 de agosto y el 14 de septiembre de 2026 sin contar caché. Alcanza para validar a un conductor dentro de un registro en línea, y en el alta de una flota completa conviene lanzar las consultas en paralelo.

¿Qué verifica cada sector en la licencia de sus conductores?

La misma respuesta sirve a sectores distintos porque cada uno mira un campo distinto. La regla común es que la licencia se valida por categoría y no por persona: un conductor con B1 vigente no está habilitado para manejar un camión, y uno con A2 vigente no lo está para un carro.

Una licencia puede quedar suspendida después del alta, así que las flotas que revalidan su base de conductores cada cierto tiempo se enteran antes del siguiente despacho y no cuando llega el comparendo. Si además necesitas el detalle de cada multa, la API de comparendos por cédula devuelve cada comparendo con su código, su estado y su valor.

¿Por qué pide el primer apellido y el nombre llega enmascarado?

Desde el 6 de agosto de 2026 el RUNT exige el primer apellido del titular para responder por una persona, y publica el nombre con asteriscos en lugar de la mayoría de las letras. PlacApi absorbió el cambio sin romper el contrato: primerApellido es opcional. Si lo envías, la consulta cuesta 1 crédito; si no, lo averiguamos a partir del documento y cuesta 2. Si no se logra averiguar, la respuesta es 400 con el código apellido_requerido y no cobra; si el registro del que lo averiguamos no responde, es 503 identidad_no_disponible con Retry-After, y tampoco cobra.

El nombre enmascarado no afecta la verificación: la licencia se identifica por el documento, que viaja completo en documentNumber, y fullName sirve para confirmar a simple vista, no como llave.

¿Cómo saber por API si una licencia de conducción está suspendida?

Se ve en dos registros, y para una decisión que importa conviene mirar los dos. En /api/licencia, una licencia con una medida llega dentro de licenses con su status, el número de resolución y las fechas de inicio y fin de la suspensión. En /api/suspension-licencia, que responde desde el SIMIT con una mediana de 2,3 segundos, llegan las banderas suspendida y cancelada con la vigencia de la medida y el organismo de tránsito que la impuso. La primera da el detalle por categoría; la segunda es la verificación rápida para quien solo necesita saber si hay una medida vigente.

¿El RUNT tiene una API pública para consultar licencias?

No para empresas y desarrolladores en general: los servicios web del RUNT están reservados a los actores del sistema de tránsito, como los organismos de tránsito y las aseguradoras. PlacApi es un servicio independiente, sin vínculo con la Concesión RUNT ni con el Ministerio de Transporte, que consulta la información de licencias que el RUNT publica y la entrega en JSON con un contrato estable: el mismo formato hoy y cuando el portal cambie por dentro.

¿Cuánto cuesta consultar una licencia de conducción por API?

1 crédito si la solicitud trae el primer apellido del titular y 2 si no lo trae, porque en ese caso lo averiguamos antes de consultar. El crédito vale 349 COP en el tramo de entrada y baja hasta 99 COP por volumen, sin mensualidad y con créditos que no vencen. Si la fuente no responde, el crédito se devuelve.

¿Se consulta por placa o por cédula?

Por documento de la persona (docType y docNumber). Las licencias son del conductor, no del vehículo, así que no se envía placa.

Ejemplo de solicitud

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

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

Parámetros, errores y ejemplos en cURL, JavaScript y Python: documentación de POST /api/licencia.

Ejemplo de respuesta

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

{
  "data": {
    "documentType": "CC",
    "documentNumber": "1020304050",
    "fullName": "J**N P***Z",
    "driverStatus": "ACTIVO",
    "citizenStatus": "ACTIVA",
    "inscriptionNumber": "20310213",
    "inscriptionDate": "08/02/2021",
    "totalLicenses": "1",
    "licenses": [
      {
        "category": "B1",
        "status": "ACTIVA",
        "licenceNumber": "885466652067",
        "otExpide": "INSTITUTO DE MOVILIDAD",
        "expeditionDate": "23/04/2025",
        "dueDate": "23/04/2035",
        "restrictions": null,
        "resolutionNumber": null,
        "startDateSuspension": null,
        "endDateSuspension": null,
        "substratum": "12345678"
      }
    ],
    "infractions": {
      "tieneMultas": "NO",
      "nroPazYSalvo": "PS-20310213"
    },
    "requests": [],
    "aptitudeCertificates": [],
    "medicalCertificates": []
  },
  "mode": "live"
}

Explicación campo por campo

Limitaciones y posibles errores

• La consulta es por persona (documento), no por placa.
• Las fechas vienen en formato DD/MM/YYYY, tal como las expone el RUNT.
• Desde el 6 de agosto de 2026 el nombre del titular llega enmascarado, porque así lo publica el RUNT; la identificación es el documento.
• Si el RUNT ciudadano no responde, la consulta devuelve error y no cobra.
• PlacApi reporta lo que el RUNT expone; no emite, renueva ni gestiona licencias.

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

Otras preguntas frecuentes

Seguir explorando

• API de comparendos por cédula→
• API de antecedentes judiciales por cédula→
• API de consulta vehicular (ficha RUNT)→
• API de multas SIMIT→
• API RUNT→
• Documentación del endpoint→
• Precios por consulta→
• API de nombre por cédula→
• API del Sisbén: grupo y clasificación→
• API del RUI: registro de ingresos→
• Récord de conductor por DNI: las licencias del MTC→