Weighbridge Ticket OCR API
Extract operational data from weighbridge tickets, scale tickets, weighment slips, quarry load tickets, and dump tickets. The API returns structured fields plus deterministic gross-tare-net validation.
Endpoint
POSThttps://api.structocr.com/v1/weighbridge-ticketPrice: 2 credits per successful request.
Request parameters
Capture the complete ticket, including headers and all gross/tare/net rows. Avoid cropping printed units or ticket identifiers.
| Parameter | Location | Required | Description |
|---|---|---|---|
| x-api-key | Header | Yes | API key from your StructOCR dashboard. |
| Content-Type | Header | Yes | Must be application/json. |
| img | JSON body | Yes | Raw Base64 or data URI. JPG, PNG, WebP, PDF; maximum decoded size 4.5MB. |
Response schema
| Field | Description |
|---|---|
| is_weighbridge_ticket | Whether the submitted document belongs to the supported ticket family. |
| document_type | Normalized ticket classification, including quarry, disposal, grain, loading, offloading, generic, or not-a-ticket. |
| ticket_number | Printed weighbridge or scale ticket identifier. |
| facility | Facility name, address, and scale ID. |
| parties | Supplier and customer names. |
| job | Job and order identifiers. |
| vehicle | Vehicle registration, trailer registration, fleet number, and driver. |
| material | Material description and printed code. |
| weights | Gross, tare, and net objects with value, unit, raw text, and normalized_kg. |
| weigh_in_datetime | First or inbound weighing timestamp when printed. |
| weigh_out_datetime | Second or outbound weighing timestamp when printed. |
| fee | Printed fee amount and currency when available. |
| confidence | Normalized high, medium, or low confidence. |
| validation | Calculated net, difference, pass/fail state, needs_review, and machine-readable review reasons. |
Code examples
curl -X POST https://api.structocr.com/v1/weighbridge-ticket \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"img":"data:image/jpeg;base64,/9j/4AAQSkZJRg..."}'Language tutorials
Follow an end-to-end integration guide for your backend stack.
200 response
{
"success": true,
"data": {
"is_weighbridge_ticket": true,
"document_type": "quarry_load_ticket",
"ticket_number": "WB-1001",
"facility": {
"name": "North Quarry",
"address": null,
"scale_id": "SCALE-2"
},
"parties": {
"supplier": "North Quarry",
"customer": "Example Civil"
},
"job": {
"job_number": "JOB-42",
"order_number": null
},
"vehicle": {
"registration": "ABC123",
"trailer_registration": null,
"fleet_number": "TRK-08",
"driver_name": null
},
"material": {
"description": "20 mm aggregate",
"code": "AGG20"
},
"weights": {
"gross": {
"value": 32500,
"unit": "kg",
"raw": "GROSS 32,500 KG",
"normalized_kg": 32500
},
"tare": {
"value": 12500,
"unit": "kg",
"raw": "TARE 12,500 KG",
"normalized_kg": 12500
},
"net": {
"value": 20000,
"unit": "kg",
"raw": "NET 20,000 KG",
"normalized_kg": 20000
}
},
"weigh_in_datetime": "2026-09-01T08:21:00",
"weigh_out_datetime": "2026-09-01T08:36:00",
"fee": {
"amount": null,
"currency": null
},
"operator_name": null,
"notes": null,
"confidence": "high",
"is_valid": true,
"validation_error": null,
"validation": {
"calculated_net_kg": 20000,
"difference_kg": 0,
"weight_check_passed": true,
"needs_review": false,
"review_reasons": []
}
}
}Error Responses
Error responses use a stable machine-readable error value. Provider and processing failures also include success: false and a safe public message.
400 Bad Request — Invalid Input
Returned when the JSON body is invalid, the img/image field is missing, or the Base64 content is malformed or empty.
Possible codes: INVALID_JSON · NO_IMAGE_DATA · INVALID_BASE64_FORMAT · INVALID_BASE64 · EMPTY_IMAGE_DATA · INVALID_REQUEST_FORMAT
{
"error": "INVALID_BASE64_FORMAT",
"message": "The image string contains illegal characters. Please ensure it's a valid Base64 encoded string without special characters."
}401 Unauthorized — Missing API Key
The x-api-key request header was not provided.
Possible codes: AUTH_FAILED
{
"error": "AUTH_FAILED"
}402 Payment Required — Insufficient Credits
The account balance is below the 2 credits required for a weighbridge ticket request.
Possible codes: INSUFFICIENT_CREDITS
{
"success": false,
"error": "INSUFFICIENT_CREDITS",
"message": "Your account balance is insufficient to complete this operation."
}403 Forbidden — Invalid or Suspended Key
The supplied API key does not exist, has been revoked, or is currently inactive.
Possible codes: INVALID_KEY · KEY_SUSPENDED
{
"error": "INVALID_KEY"
}413 Payload Too Large
The decoded JPG, PNG, WebP, or PDF exceeds the documented 4.5MB limit.
Possible codes: FILE_TOO_LARGE
{
"error": "FILE_TOO_LARGE",
"message": "The decoded file exceeds the maximum allowed size of 4.5MB."
}415 Unsupported Media Type
Use application/json and provide Base64 content whose detected format is JPG, PNG, WebP, or PDF.
Possible codes: INVALID_CONTENT_TYPE_USE_JSON · UNSUPPORTED_FILE_FORMAT
{
"error": "UNSUPPORTED_FILE_FORMAT",
"message": "Supported formats are JPG, PNG, WebP, and PDF."
}422 Unprocessable Entity — Policy Violation
The submitted image could not be processed because an upstream model safety policy blocked it.
Possible codes: CONTENT_POLICY_VIOLATION
{
"success": false,
"error": "CONTENT_POLICY_VIOLATION",
"message": "The document content could not be processed due to safety policies."
}500 Internal Server Error
A non-retryable extraction, response parsing, or internal processing error occurred.
Possible codes: PROCESSING_ERROR
{
"success": false,
"error": "PROCESSING_ERROR",
"message": "An internal error occurred while processing the document. Please contact support if the problem persists."
}502 Bad Gateway — Regional Routing Failure
The configured regional model route and its fallback were temporarily unavailable. Retry with backoff.
Possible codes: EDGE_ROUTING_GATEWAY_ERROR
{
"success": false,
"error": "EDGE_ROUTING_GATEWAY_ERROR",
"message": "StructOCR experienced a localized routing anomaly at our border gateway. The request environment has been isolated. Please re-submit in a few moments."
}503 Service Unavailable — System Busy
Upstream model capacity or rate limiting was reached. Retry with exponential backoff.
Possible codes: SYSTEM_BUSY
{
"success": false,
"error": "SYSTEM_BUSY",
"message": "StructOCR is currently processing a high volume of requests. Please try again in a few seconds."
}Status Code Definitions
| Status | Error code | Recommended handling |
|---|---|---|
| 200 | SUCCESS | Use the extracted fields and inspect validation.needs_review. |
| 400 | INVALID_JSON · NO_IMAGE_DATA · INVALID_BASE64_FORMAT · INVALID_BASE64 · EMPTY_IMAGE_DATA · INVALID_REQUEST_FORMAT | Returned when the JSON body is invalid, the img/image field is missing, or the Base64 content is malformed or empty. |
| 401 | AUTH_FAILED | The x-api-key request header was not provided. |
| 402 | INSUFFICIENT_CREDITS | The account balance is below the 2 credits required for a weighbridge ticket request. |
| 403 | INVALID_KEY · KEY_SUSPENDED | The supplied API key does not exist, has been revoked, or is currently inactive. |
| 413 | FILE_TOO_LARGE | The decoded JPG, PNG, WebP, or PDF exceeds the documented 4.5MB limit. |
| 415 | INVALID_CONTENT_TYPE_USE_JSON · UNSUPPORTED_FILE_FORMAT | Use application/json and provide Base64 content whose detected format is JPG, PNG, WebP, or PDF. |
| 422 | CONTENT_POLICY_VIOLATION | The submitted image could not be processed because an upstream model safety policy blocked it. |
| 500 | PROCESSING_ERROR | A non-retryable extraction, response parsing, or internal processing error occurred. |
| 502 | EDGE_ROUTING_GATEWAY_ERROR | The configured regional model route and its fallback were temporarily unavailable. Retry with backoff. |
| 503 | SYSTEM_BUSY | Upstream model capacity or rate limiting was reached. Retry with exponential backoff. |
Live API test
Live Demo: Weighbridge Ticket OCR Scanner
No registration required. Upload a file to test the extraction.
Drop files here or click to browse
JPG · PNG · WebP · up to 500 files · max 4.5 MB each