Nexcar

Cases

A case represents a vehicle. Use this resource to obtain the `case_id` you'll attach documents to.

Endpoints#

MethodPathDescription
POST/v1/casesCreate a case, optionally with initial documents
GET/v1/cases/{case_id}Read the case and its documents (with OCR)
DELETE/v1/cases/{case_id}Soft-delete the case
GET/v1/cases/{case_id}/namesNames consolidated from all documents
GET/v1/cases/{case_id}/vinsPrimary VIN and all VINs detected per document
GET/v1/cases/{case_id}/platesLicense plates detected in the case with vigencia data
GET/v1/cases/{case_id}/repuveREPUVE registration data for the vehicle
GET/v1/cases/{case_id}/pedimentoMost recent customs entry (pedimento) result
POST/v1/cases/{case_id}/pedimentoTrigger a new customs entry lookup from OCR data
GET/v1/cases/{case_id}/rapiMost recent RAPI (FGJCDMX) criminal activity lookup result
POST/v1/cases/{case_id}/rapiTrigger a new RAPI lookup for the case's primary VIN
POST/v1/cases/{case_id}/taxesTrigger a bulk tenencia lookup for all plates in the case
GET/v1/cases/{case_id}/invoicesInvoices with their processing status
GET/v1/cases/{case_id}/metadataBusiness metadata attached to the case
POST/v1/cases/{case_id}/metadataAppend an entry to the metadata history
POST/v1/cases/{case_id}/processBulk-process the case's documents
GET/v1/cases/{case_id}/statusStatus of the latest processing job

POST /v1/cases — Create a case#

Creates a case for a vehicle. You may attach documents in the same call or upload them later.

Body#

FieldTypeRequiredDescription
internal_idstringYesCase identifier on your side. Cannot be empty.
statusstringYesInitial state of the case (e.g. processing, nuevo).
vehicle_originstringNoNacional (default) or Importado.
initial_statusstringNoAlternative initial state when a status catalog is configured.
use_caseUUIDNoUse case for the file when a catalog applies.
metadataobjectNoAdditional business data (see below).
filesarrayNoDocuments to upload immediately.

curl example#

curl -X POST https://api.nexcar.mx/v1/cases \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "internal_id": "EXP-2026-0001",
    "status": "processing",
    "vehicle_origin": "Nacional",
    "metadata": {
      "numero_siniestro": "128890890",
      "tipo_afectado": "TERCERO",
      "nombre_afectado": "JUAN PÉREZ GARCÍA"
    },
    "files": [
      {
        "url": "https://your-storage.example.com/invoice.pdf",
        "mime_type": "application/pdf",
        "document_type": "factura"
      },
      {
        "url": "https://your-storage.example.com/owner-id.jpg",
        "mime_type": "image/jpeg",
        "document_type": "ine"
      }
    ]
  }'

Request body#

{
  "internal_id": "EXP-2026-0001",
  "status": "processing",
  "vehicle_origin": "Nacional",
  "metadata": {
    "numero_siniestro": "128890890",
    "tipo_afectado": "TERCERO",
    "nombre_afectado": "JUAN PÉREZ GARCÍA"
  },
  "files": [
    {
      "url": "https://your-storage.example.com/invoice.pdf",
      "mime_type": "application/pdf",
      "document_type": "factura"
    },
    {
      "url": "https://your-storage.example.com/owner-id.jpg",
      "mime_type": "image/jpeg",
      "document_type": "ine"
    }
  ]
}

Responses#

201 Created — case created without files:

{ "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c", "status": "completed" }

202 Accepted — case created with files queued for processing:

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "job_id": "31b4ecf2-9a0b-4f98-8a91-2ab6e93f4f10",
  "total_files": 2,
  "status": "processing"
}

Common errors#

HTTPCodeCause
400VALIDATION_ERRORMissing status or empty internal_id
400DUPLICATE_INTERNAL_IDA case with that internal_id already exists with files
422INVALID_STATUSstatus is not part of the configured catalog

GET /v1/cases/{case_id}#

Returns the case and all of its documents along with their OCR (when available).

curl example#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c \
  -H "x-api-key: your_api_key"

Response#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "internal_id": "EXP-2026-0001",
  "status": "nuevo",
  "vehicle_origin": "Nacional",
  "documents": [
    {
      "document_id": "abc123",
      "type": "factura",
      "mime_type": "application/pdf",
      "url": "https://...nexcar.mx/storage/.../invoice.pdf",
      "parsed_data": { "vin": "3VWFE21C04M000001", "monto_total": 285000 }
    }
  ]
}

DELETE /v1/cases/{case_id}#

Marks the case as inactive. Files are not physically deleted; the case stops appearing in lookups and reports.

curl -X DELETE https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c \
  -H "x-api-key: your_api_key"

POST /v1/cases/{case_id}/process#

Queues the bulk processing (OCR + extraction) of the documents in the case. Useful when you uploaded files without type and want to run the flow as a batch.

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/process \
  -H "x-api-key: your_api_key"

{ "job_id": "31b4ecf2-9a0b-4f98-8a91-2ab6e93f4f10", "status": "processing" }

Track progress with GET /v1/cases/{case_id}/status.

GET /v1/cases/{case_id}/plates#

Returns the license plates detected across the case's documents, enriched with VIN, motor number, owner name and — for plates registered in Estado de México — the current vigencia data (status, validity dates and previous plate, when applicable) from the official portal.

The list is built and persisted automatically as part of the case processing pipeline. This endpoint is read-only.

curl example#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/plates \
  -H "x-api-key: your_api_key"

Response#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "internal_id": "EXP-2026-0001",
  "plates": [
    {
      "plate": "MJM626C",
      "entity": "MEX",
      "document_type": "vehicle_certificate",
      "document_date": "01/09/2025",
      "file_id": "0126537c-8dad-402a-a559-0bbbcafd53a3",
      "ocr_id": "f2dd2062-d11d-480b-9c0b-1b6d03b6f1df",
      "niv": "JN1BE6DSXS9121418",
      "motor_number": "QR258585700Q",
      "owner_name": null,
      "plate_status": "Vigente",
      "plate_valid_from": "01/09/2025",
      "plate_valid_until": "01/09/2030",
      "previous_plate": null,
      "previous_plate_lookup_status": null
    }
  ]
}

Field reference#

FieldTypeDescription
platestringNormalized plate number (uppercase, no separators)
entitystringThree-letter state code (MEX, NLE, JAL, …)
document_typestringSource document: certificate_title, tax_payment, alta_vehicular, vehicle_certificate, vehicle_plate, lumo_checklist or repuve
document_datestringDate associated with the source document (DD/MM/YYYY when available)
nivstring | nullVehicle VIN (17 chars when available, partial otherwise)
motor_numberstring | nullEngine number from the source document
owner_namestring | nullOwner as declared in the source document
plate_statusstring | nullCurrent plate status returned by the portal: Vigente, Vencida or Inactiva
plate_valid_fromstring | nullStart of current plate validity (DD/MM/YYYY)
plate_valid_untilstring | nullEnd of current plate validity (DD/MM/YYYY)
previous_platestring | nullPrevious plate number, when one was emitted before the current one
previous_plate_lookup_statusstring | nullLookup state — see below

previous_plate_lookup_status values#

ValueMeaning
nullThe lookup does not apply (plate not registered in MEX) or the portal confirmed there is no previous plate
"pending"Lookup in progress in background — re-query in a few seconds
"found"Portal returned a previous plate (populated in previous_plate)
"error"Lookup failed after retries (portal down, parsing error, etc.)

The same plate may appear in multiple rows when it was detected in more than one document. All rows sharing the same plate value carry the same plate_status, vigencia dates and previous_plate_* fields once the background lookup finishes.

Common errors#

HTTPCause
404Case not found, inactive, or plates have not been computed yet for this case

GET /v1/cases/{case_id}/repuve#

Returns the most recent REPUVE job for the case. If the job ended in error but a valid response from placas.info is available, the endpoint auto-recovers and returns the correct data.

curl example#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/repuve \
  -H "x-api-key: your_api_key"

Response#

{
  "codigo": "ok",
  "info": {
    "niv": "3N6AD35A9LK875826",
    "placa": "Y83BGS",
    "marca": "NISSAN",
    "modelo": "NP300/NP300 FRONTIER/FRONTIER",
    "tipo": "CAB. Y CHASIS ESTACAS",
    "clase": "CAMIONETA",
    "anio_modelo": 2020,
    "entidad_emplacado": "CIUDAD DE MEXICO",
    "fecha_inscripcion": "22/09/20",
    "fecha_actualizacion": "12/10/24",
    "reporte_robo": [
      { "tipo_reporte": "FGJ", "estatus": "SIN REPORTE DE ROBO" },
      { "tipo_reporte": "OCRA", "estatus": "SIN REPORTE DE ROBO" }
    ],
    "robo_usa_can": { "tiene_robo": false },
    "aviso_judicial": { "tiene_aviso_judicial": false }
  },
  "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437",
  "job_status": "completed"
}

Field reference#

FieldTypeDescription
codigostringok — REPUVE data available. error — all sources failed. processing — job still in progress.
infoobject | nullVehicle registration data from REPUVE. null when the vehicle is not registered or the job has not completed yet.
info.nivstringVehicle identification number (VIN)
info.placastring | nullLicense plate on record in REPUVE
info.marcastringMake
info.modelostringModel
info.anio_modelointegerModel year
info.entidad_emplacadostring | nullState where the plate was registered
info.fecha_inscripcionstring | nullREPUVE registration date
info.fecha_actualizacionstring | nullLast update date in REPUVE
info.reporte_roboarrayTheft reports from FGJ and OCRA sources
info.robo_usa_canobjectUSA/Canada theft report status
info.aviso_judicialobjectJudicial notice status
job_idUUIDInternal job identifier
job_statusstringcompleted, error, processing or pending

Common errors#

HTTPCause
404Case not found, inactive, or no REPUVE query has been run for this case

GET /v1/cases/{case_id}/pedimento#

Returns the most recent customs entry (pedimento) result for the case. Data is read from pedimento_responses (legacy pipeline) and processing_jobs (v1 API), deduplicated by content, and sorted by recency.

curl example#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/pedimento \
  -H "x-api-key: your_api_key"

Response#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437",
  "status": "completed",
  "source": "processing_jobs",
  "result": {
    "success": true,
    "data": { "pedimento": "39317003384", "aduana": "MANZANILLO", "vin": "LUCGM6669J3104807" }
  }
}

Common errors#

HTTPCause
404Case not found, inactive, or no pedimento query has been run for this case. Call POST /v1/cases/{id}/pedimento first.

GET /v1/cases/{case_id}/taxes (without ?plate)#

Returns all tenencia results for every plate in the case, grouped by plate. Results are read from processing_jobs across all sources (background pipeline and on-demand v1).

When ?plate is supplied the original single-plate behavior is used unchanged — see the existing documentation.

curl example#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/taxes \
  -H "x-api-key: your_api_key"

Response#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "plates_count": 2,
  "taxes": [
    {
      "plate": "MES452A",
      "job_id": "abc123",
      "status": "completed",
      "source": "api_v1_cases_taxes_bulk",
      "result": { "codigo": "ok", "info": [...] },
      "created_at": "2026-06-05T10:00:00+00:00"
    }
  ]
}

POST /v1/cases/{case_id}/taxes#

Triggers a bulk tenencia lookup for all unique plates in the case (main plates + previous plates), using GET /v1/cases/:id/plates data internally (no HTTP). One processing_jobs child row is created per plate, each with its own job_id, external_payload and external_response. The workflow runs in Temporal (invoice-background-queue).

curl example#

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/taxes \
  -H "x-api-key: your_api_key"

Response 202 Accepted#

{
  "job_id": "31b4ecf2-9a0b-4f98-8a91-2ab6e93f4f10",
  "plates": ["MES452A", "NDJ3622"],
  "status": "pending"
}

Poll GET /v1/cases/{case_id}/taxes (without ?plate) to see the results per plate as they complete.

Common errors#

HTTPCause
400No plates found for this case. Call POST /v1/cases/{id}/plates first.
404Case not found or inactive

POST /v1/cases/{case_id}/pedimento#

Triggers a new customs entry lookup using data extracted from the OCR of the case's primary document (the invoice linked to the main VIN). Runs asynchronously in Temporal. Returns a job_id immediately; poll GET /v1/cases/{id}/pedimento for the result.

The required parameters (aduana, ano_vehiculo) are read from the OCR automatically. If they are not present in the document, the endpoint returns a 400 listing the missing fields.

curl example#

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/pedimento \
  -H "x-api-key: your_api_key"

Response 202 Accepted#

{ "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437", "status": "pending" }

Common errors#

HTTPCause
400No primary VIN found, or required OCR fields (aduana, ano_vehiculo) are missing
404Case not found or inactive

GET /v1/cases/{case_id}/rapi#

Returns the most recent RAPI (FGJCDMX criminal activity registry) lookup result for the case. Data is read from rapi_responses (legacy pipeline) and processing_jobs (v1 API), deduplicated by content, and sorted by recency.

curl example#

curl https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/rapi \
  -H "x-api-key: your_api_key"

Response#

{
  "case_id": "7040fd87-5f49-4187-b2a3-b4a19670825c",
  "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437",
  "status": "completed",
  "source": "processing_jobs",
  "result": { ... }
}

Common errors#

HTTPCause
404Case not found, inactive, or no RAPI query has been run. Call POST /v1/cases/{id}/rapi first.

POST /v1/cases/{case_id}/rapi#

Triggers a RAPI lookup for the case's primary VIN (from GET /v1/cases/:id/vins). Runs asynchronously in Temporal (invoice-background-queue). Returns a job_id immediately.

curl example#

curl -X POST https://api.nexcar.mx/v1/cases/7040fd87-5f49-4187-b2a3-b4a19670825c/rapi \
  -H "x-api-key: your_api_key"

Response 202 Accepted#

{ "job_id": "4a201139-7945-4ae7-8a17-dc8e048c7437", "vin": "3N6AD35A9LK875826", "status": "pending" }

Common errors#

HTTPCause
400No primary VIN found. Process documents first with POST /v1/cases/{id}/process.
404Case not found or inactive
PreviousAuthentication
NextDocuments