Skip to main content

Orders & Comparison

Read every order of a customs pipeline with field-by-field comparison against the filed declaration, source documents, seven checks, and a ready flag per order.

GET /v1/customs-declaration/declarations returns every order the pipeline assembled, one per LRN, highest LRN first. Each order combines the extracted header values (sender, receiver, route, procedure, plates, document_date), the filed declaration's date (declared_on, null when no filed declaration matches the LRN) and a filed flag, the order's member documents, the comparison rows, the seven checks, a tally and the ready flag. The envelope names the pipeline, the stage that supplied the comparison, the data_product_id where the orders are reviewed, and generated_at.

Each comparison row pairs an extracted field with a column of the filed declaration: field_key, label, ref_column, extracted, filed, and a state. The row also carries where the value came from: confidence, cell_status, source_document_id, source_filename, and source_text, the text on the source document the value was read from when it was located. scored is true for the fields the Spec's stage maps, and false for rows shown for reference, whose differences are reported as info and never count against the order.

The states are match, partial (similar but not equal), mismatch, missing (something is filed, nothing was extracted), no_reference (nothing is filed for the field, or the order has no filed declaration) and empty (neither side has a value). The tally counts the scored rows in match, partial, mismatch and missing. How a value compares depends on the field: weights match within 1 kg and package counts exactly; tariff codes match on the first 8 digits and are partial on the first 4; plates match when every plate agrees and are partial when some do; CMR numbers match on equal digits; other text compares after normalization and matches on equality, containment or similarity of 85 % or more, with partial from 60 %, unless the stage mapping is strict, which accepts only equality.

GET/v1/customs-declaration/declarations

Query parameters

pipeline_iduuidAn eligible pipeline. When omitted, the newest completed eligible pipeline, else the newest eligible one.
statusstringready keeps orders with no failing check, review keeps orders with at least one. Any other value applies no status filter.
qstringCase-insensitive substring over LRN, sender, receiver and plates.

Response fields

pipelineobjectid, name and status of the pipeline read.
stageobjectid, name, reference_data_id and reference_name of the comparison stage.
data_product_iduuid | nullThe pipeline's data product, where its orders are reviewed.
generated_atstring (date-time)When the response was computed.
items[]arrayThe orders. status and q narrow items only; the envelope is unaffected.

Order fields (items[])

lrnstringThe order's local reference number.
record_document_id, record_idstring, string | nullThe composed record the order was read from.
sender, receiver, procedure, plates, document_datestring | nullExtracted header values.
routestring | nullLoading and delivery country codes joined with an arrow.
declared_onstring | nullWhen the declaration was filed; null when no filed declaration matches.
filedbooleanTrue when a filed declaration matches the LRN.
consignmentsobject[]The order's consignment lines as assembled.
normalisation_logstring | nullThe normalisation log recorded for the order, when there is one.
documents[]arrayMember documents: document_id, filename, lrn, type, cmr_number, total_gross_weight, total_packages.
comparison[]arrayRows: field_key, label, ref_column, extracted, filed, state, note, scored, confidence, cell_status, source_document_id, source_filename, source_text.
checks[]arrayThe seven checks: id, title, status (pass, fail or na), message, fields, detail.
tallyobjectCounts of scored rows: match, partial, mismatch, missing.
readybooleanTrue when no check failed.

cURL: Orders that need review, searched by plate

curl "https://api.talonic.com/v1/customs-declaration/declarations?pipeline_id=$PIPELINE_ID&status=review&q=AB-CD" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response: One order (excerpt)

{
  "pipeline": { "id": "9c4e7a12-6d03-4b58-b1f7-3e8a0d5c2f46", "name": "October consignments", "status": "completed" },
  "stage": {
    "id": "4a1d8e60-2c97-4f35-a0b6-e7d3c9f15b82",
    "name": "Compare with filed declarations",
    "reference_data_id": "d5b02c7e-18a4-4e69-93f1-6a0e4c8b7d25",
    "reference_name": "Filed declarations"
  },
  "data_product_id": "b83f6d29-0e41-4a7c-9d15-2c6e8a4f1b30",
  "generated_at": "2026-10-21T10:05:33.000Z",
  "items": [
    {
      "lrn": "26DE0012345678",
      "record_document_id": "5e0a9c47-3b18-4d62-8f2a-7c1d6e9b4a03",
      "sender": "Rhein Logistik GmbH",
      "receiver": "Piraeus Trading SA",
      "route": "DE → GR",
      "plates": "AB-CD 123 / EF-GH 456",
      "declared_on": "2026-10-18",
      "filed": true,
      "documents": [
        { "document_id": "a2c8e1f5-7d34-4b90-a6e2-9f0b3c5d8e17", "filename": "cmr-0417.pdf", "lrn": "26DE0012345678", "type": "CMR", "cmr_number": "0417", "total_gross_weight": "24.130 kg", "total_packages": "33" }
      ],
      "comparison": [
        {
          "field_key": "gross_weight_kg",
          "label": "Gross weight (kg)",
          "ref_column": "gross_weight_kg",
          "extracted": 24130,
          "filed": 24100,
          "state": "mismatch",
          "note": "Off by 30 kg (0.1 %)",
          "scored": true,
          "confidence": 0.93,
          "cell_status": null,
          "source_document_id": "a2c8e1f5-7d34-4b90-a6e2-9f0b3c5d8e17",
          "source_filename": "cmr-0417.pdf",
          "source_text": "24.130 kg"
        }
      ],
      "checks": [
        { "id": "weight-agree", "title": "Weight agrees across documents (±3 %)", "status": "pass", "message": null, "fields": ["gross_weight_kg"], "detail": "CMR: 24.130 kg" }
      ],
      "tally": { "match": 9, "partial": 0, "mismatch": 1, "missing": 0 },
      "ready": true
    }
  ]
}
The example order is ready and still has a mismatch row. ready reflects the seven blocking checks only; read comparison and tally for field-level agreement with the filed declaration. Filter with status=review for orders with a failing check, not for orders with a difference.

Frequently asked questions

Why does an order have state no_reference on every row?+
No filed declaration matches its LRN, so filed is false and declared_on is null. Each scored row then reports no_reference with the note that no filed declaration exists for the order. Check that the declaration is in the reference table the stage names, under the same LRN.
What does the status parameter filter?+
Only items. status=ready keeps orders with no failing check, status=review keeps orders with at least one, and any other value applies no filter. The pipeline, stage, data_product_id and generated_at fields of the envelope are unaffected.
What is source_text?+
The text on the source document the value was read from, when the platform located it. It is null when the location is unknown. Together with source_document_id and source_filename it lets a reviewer jump to the evidence for a mismatch.
Why are some rows not scored?+
Rows for fields the Spec's stage does not map are appended for reference. Their differences are reported as info because the filed record stores them differently, for example a country code instead of a town, and they never count in tally.

Related

Customs Declaration Overview
Eligible Pipelines
Issues Worklist
Error Format