ID scan — API Help

POST /api/upload

Upload an image of a Bolivian identity document, driver's license, or vehicle registration and receive structured, machine-readable JSON with extracted fields.

Method	POST
URL	`/api/upload`
Content-Type	`multipart/form-data`

Request

Field	Type	Required	Description
`file`	binary	Yes	Image file in JPG, PNG, or GIF format

Accepted formats: .jpg, .jpeg, .png, .gif. Unsupported formats return 400.

Success Response 200

The response always contains a documento field indicating the document type, plus three nested objects. Exactly one nested object is populated; the other two are null.

Identity Card (Carnet de Identidad)

{
  "documento": "carnet",
  "carnet": {
    "numero_de_cedula": "1234567",
    "nombre": "Juan",
    "nombres": "Juan Carlos",
    "apellidos": "Perez Quispe",
    "fecha_nacimiento": "1990-01-01",
    "lugar_nacimiento": "La Paz",
    "ocupacion": "Ingeniero",
    "estado_civil": "Soltero",
    "direccion": "Calle 123 #45",
    "fecha_emision": "2020-01-01",
    "fecha_vencimiento": "2025-01-01"
  },
  "licencia": null,
  "ruat": null,
  "mensaje": null
}

Driver's License (Licencia para Conducir)

{
  "documento": "licencia",
  "carnet": null,
  "licencia": {
    "nombre": "Maria",
    "nombres": "Maria Elena",
    "apellidos": "Lopez Garcia",
    "sexo": "F",
    "categoria": "P",
    "nacionalidad": "Boliviana",
    "numero_de_licencia": "9876543",
    "fecha_emision": "2021-06-01",
    "fecha_nacimiento": "1985-03-15",
    "fecha_vencimiento": "2026-06-01"
  },
  "ruat": null,
  "mensaje": null
}

Vehicle Registration (RUAT)

{
  "documento": "ruat",
  "carnet": null,
  "licencia": null,
  "ruat": {
    "placa": "1234ABC",
    "gobierno_municipal": "La Paz",
    "clase": "Automovil",
    "marca": "Toyota",
    "modelo": "Corolla",
    "tipo_vehiculo": "Sedan",
    "sub_tipo_vehiculo": "",
    "servicio": "Particular",
    "numero_motor": "1ZZ-1234567",
    "numero_chasis": "JT1234567890",
    "cilindrada": "1800",
    "peso": "1200",
    "traccion": "Delantera",
    "numero_ruedas": "4",
    "color": "Blanco",
    "numero_plazas": "5",
    "combustible": "Gasolina",
    "tipo_motor": "",
    "propietario": "Juan Perez",
    "direccion": "Av. Siempre Viva 742",
    "documento_identidad": "1234567"
  },
  "mensaje": null
}

Field Reference

Carnet Fields (11)

Field	Type	Description
`numero_de_cedula`	string	National ID number
`nombre`	string	First name
`nombres`	string	Full given names
`apellidos`	string	Last names
`fecha_nacimiento`	string	Date of birth
`lugar_nacimiento`	string	Place of birth
`ocupacion`	string	Occupation
`estado_civil`	string	Marital status
`direccion`	string	Address
`fecha_emision`	string	Issue date
`fecha_vencimiento`	string	Expiration date

Licencia Fields (10)

Field	Type	Description
`nombre`	string	First name
`nombres`	string	Full given names
`apellidos`	string	Last names
`sexo`	string	Gender (M/F)
`categoria`	string	License category (P, A, B, C)
`nacionalidad`	string	Nationality
`numero_de_licencia`	string	License number
`fecha_emision`	string	Issue date
`fecha_nacimiento`	string	Date of birth
`fecha_vencimiento`	string	Expiration date

RUAT Fields (21)

Field	Type	Description
`placa`	string	License plate
`gobierno_municipal`	string	Municipal government
`clase`	string	Vehicle class
`marca`	string	Brand
`modelo`	string	Model
`tipo_vehiculo`	string	Vehicle type
`sub_tipo_vehiculo`	string	Vehicle subtype
`servicio`	string	Service type
`numero_motor`	string	Engine number
`numero_chasis`	string	Chassis number
`cilindrada`	string	Engine displacement
`peso`	string	Weight
`traccion`	string	Drive type
`numero_ruedas`	string	Number of wheels
`color`	string	Color
`numero_plazas`	string	Number of seats
`combustible`	string	Fuel type
`tipo_motor`	string	Engine type
`propietario`	string	Owner name
`direccion`	string	Owner address
`documento_identidad`	string	Owner ID number

Error Responses

Status	Scenario	Example
400	Unsupported file format	`{"documento":"desconocido","mensaje":"Unsupported file format, file: doc.bmp",...}`
400	LLM returned an error	`{"documento":"desconocido","mensaje":"Error with LLM timeout",...}`
400	LLM response was not valid JSON	`{"documento":"desconocido","mensaje":"Failed to decode JSON from LLM response",...}`
400	Document could not be identified	`{"documento":"desconocido","mensaje":"documento invalido",...}`

curl Example

curl -X POST http://localhost:5205/api/upload \
  -F "file=@carnet_frontal.jpg"

Corner Cases & Integration Notes

Always check documento first. Read the type, then access the corresponding nested object. The other two are always null.
All fields are strings. Even numeric-looking fields like numero_de_cedula or cilindrada are returned as strings. Dates are typically YYYY-MM-DD but may be free-form text if the LLM cannot parse them.
Missing values are empty strings. Fields the LLM cannot read come back as "", never null. Nested objects are null only when the document type does not match.
Strip whitespace. The LLM may include leading or trailing whitespace in field values. Always .strip() before use.
Low-quality or partial images will likely return documento: "desconocido" with a descriptive mensaje.
Only Bolivian documents are recognized. Foreign IDs, passports, or unrelated images will return desconocido.
Response time varies (1-5 seconds typically). The LLM processes the image server-side; no streaming or partial results.
No authentication required for this endpoint. The service is designed for internal BPM-to-service communication behind a secure network.

API Reference