---
title: "RUNT Citizen by Document"
method: POST
path: "/co/runt/citizen-by-document/v1"
tags: ["Colombia", "RUNT"]
---

# RUNT Citizen by Document

`POST /co/runt/citizen-by-document/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/runt/citizen-by-document/v1`
- Auth: HTTP bearer

Look up a person in RUNT (Registro Único Nacional de Tránsito) by identification document: the driver record (name, registration id and date, person and driver status), every driving licence with its categories, issue and expiry dates, restrictions, retention, suspension and cancellation, traffic-fine standing (paz y salvo), procedure requests (solicitudes), driving-aptitude and medical certificates with their detail, CUPL registrations, SICOV validations, ANSV payments and identity-validation history. `document_type` defaults to `CC`. `first_surname` is optional: when omitted, the surname on record is used. `found: false` when the registry has no record for the document.

Supports async delivery: set `Prefer: wait=N` for an inline result, pass `callback_url` to receive a POST when ready, or poll `GET /jobs/{id}`.

## Headers

- `Idempotency-Key` string
- `Prefer` string

## Request body

- object
  - `document_type` 'CC' | 'CE' | 'TI' | 'RC' | 'PA' | 'PPT': Colombian document type. Defaults to `CC`.
  - `document_number` string, required: Document number (alphanumeric with hyphens allowed).
  - `first_surname` string: First surname (primer apellido). Optional: when omitted, the surname on record is used.
  - `callback_url` string, uri: POST the job result here when it finishes.

## Response `200`

Successful response

- RuntCitizenResponse
  - `data` RuntCitizenData, required
    - `found` boolean, required
    - `document_type` string, required
    - `document_number` string, required
    - `first_surname` string, nullable, required
    - `person` object, nullable, required
      - `full_name` string, nullable, required
      - `registration_id` string, nullable, required
      - `registration_date` string, nullable, required
      - `person_status` string, nullable, required
      - `driver_status` string, nullable, required
      - `has_licenses` boolean, nullable, required
    - `licenses` object[], required
      - `license_number` string, nullable, required
      - `issuing_authority` string, nullable, required
      - `issue_date` string, nullable, required
      - `status` string, nullable, required
      - `is_retained` boolean, nullable, required
      - `restrictions` string, nullable, required
      - `cancellation_date` string, nullable, required
      - `suspension_start_date` string, nullable, required
      - `suspension_end_date` string, nullable, required
      - `resolution_number` string, nullable, required
      - `cancelling_authority` string, nullable, required
      - `categories` object[], required
        - `category` string, nullable, required
        - `issue_date` string, nullable, required
        - `expiry_date` string, nullable, required
        - `exam_expiry_date` string, nullable, required
        - `previous_category` string, nullable, required
    - `fines` object, nullable, required
      - `has_fines` boolean, nullable, required
      - `clearance_number` string, nullable, required
    - `requests` object[], required
      - `request_number` string, nullable, required
      - `request_date` string, nullable, required
      - `identifier` string, nullable, required
      - `status` string, nullable, required
      - `procedure_status` string, nullable, required
      - `procedure` string, nullable, required
      - `procedures_completed` number, nullable, required
      - `entity` string, nullable, required
      - `registry` string, nullable, required
      - `validation_type` string, nullable, required
      - `validation_description` string, nullable, required
    - `aptitude_certificates` object[], required
      - `certificate_number` string, nullable, required
      - `certificate_type` string, nullable, required
      - `status` string, nullable, required
      - `center_name` string, nullable, required
      - `issue_date` string, nullable, required
      - `expiry_date` string, nullable, required
      - `request_number` string, nullable, required
      - `request_date` string, nullable, required
      - `fua_number` string, nullable, required
      - `procedure` string, nullable, required
      - `category` string, nullable, required
      - `restrictions` string, nullable, required
      - `limitations` string, nullable, required
      - `limitation_expiry_date` string, nullable, required
      - `elements_to_overcome_limitations` string, nullable, required
      - `traffic_authority` string, nullable, required
    - `medical_certificates` object[], required
      - `certificate_number` string, nullable, required
      - `center_name` string, nullable, required
      - `issue_date` string, nullable, required
      - `expiry_date` string, nullable, required
      - `status` string, nullable, required
      - `request_number` string, nullable, required
      - `request_date` string, nullable, required
      - `fua_number` string, nullable, required
      - `procedure` string, nullable, required
      - `category` string, nullable, required
      - `restrictions` string, nullable, required
      - `limitations` string, nullable, required
      - `limitation_expiry_date` string, nullable, required
      - `elements_to_overcome_limitations` string, nullable, required
      - `traffic_authority` string, nullable, required
    - `cupl_registrations` object[], required
      - `cupl_number` string, nullable, required
      - `traffic_authority` string, nullable, required
      - `issue_date` string, nullable, required
      - `status` string, nullable, required
    - `sicov_validations` object[], required
      - `validation_date` string, nullable, required
      - `status` string, nullable, required
      - `description` string, nullable, required
      - `plate` string, nullable, required
    - `ansv_payments` object[], required
      - `registration_date` string, nullable, required
      - `center_name` string, nullable, required
      - `category` string, nullable, required
      - `certificate_type` string, nullable, required
      - `status` string, nullable, required
    - `identity_validation` object, nullable, required
      - `user_status` string, nullable, required
      - `unlock_date` string, nullable, required
      - `validations` object[], required
        - `validation_date` string, nullable, required
        - `status` string, nullable, required
        - `description` string, nullable, required
        - `plate` string, nullable, required

## Other responses

- `202`: Accepted — the result is being computed asynchronously. Poll `job.status_url` (GET /jobs/{id}) or supply `callback_url` to have the result POSTed to you. Returned when `Prefer: wait` elapses before completion, or immediately when `callback_url` is set.
- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)