The Scale API lets partners push scale tickets — with materials, quantities, and inbound/outbound flow data — into the Hauler Hero platform. Call this API whenever a scale ticket is created or updated in your system.
- A
HERO-API-KEYissued by Hauler Hero. Each Hauler Hero account has a unique API key. See Authentication. - Base URL:
https://api.haulerhero.com
- Build the ticket payload with site identification, at least one material, and optional inbound/outbound flow data.
- Send
POST /hero-api/v1/ticketswith the payload and yourHERO-API-KEYheader. Call this endpoint every time a scale ticket is created or updated in your system. - Store the returned
disposalTicketId— it's the Hauler Hero identifier for the ticket and is required to reference it later. - Handle errors per the response code table below.
| Field | Required | Notes |
|---|---|---|
siteId | Yes | UUID of the disposal site |
materials | Yes | Array with at least one item |
materials[].id | Yes | UUID of the material |
materials[].name | Yes | Material name (e.g., "Paper") |
materials[].quantity | Yes | Quantity as a number |
materials[].unitOfMeasure | Yes | One of: Ton, Gallon, Pound, Kilogram, Cubic Yard, Cubic Meter, Item |
materials[].unitPriceCents | No | Unit price in cents (per the spec: 15.50 represents $0.155) |
inboundFlow | No | Provide if the ticket has inbound flow data |
inboundFlow.ticketNumber | Yes, if inboundFlow is present | Your system's unique inbound ticket number |
inboundFlow.updatedAt | Yes, if inboundFlow is present | ISO 8601 timestamp |
outboundFlow | No | Provide if the ticket has outbound flow data |
outboundFlow.ticketNumber | Yes, if outboundFlow is present | Your system's unique outbound ticket number |
outboundFlow.updatedAt | Yes, if outboundFlow is present | ISO 8601 timestamp |
customFields | No | Map of string key/value pairs for integration-specific data (driver name, route, vehicle ID, customer reference, etc.) |
For full schema definitions and example payloads see the Schemas section of the Scale API reference.
| Code | Error code | Meaning | Action |
|---|---|---|---|
200 | — | Ticket created successfully | Store disposalTicketId |
400 | INVALID_PAYLOAD | Missing or malformed fields | Fix the field named in the error message and retry |
401 | UNAUTHORIZED | API key invalid or missing | Verify the HERO-API-KEY header is present and correct |
422 | VALIDATION_ERROR | Business-rule violation (e.g., referenced material ID doesn't exist) | Check that siteId and materials[].id exist in Hauler Hero |
500 | INTERNAL_ERROR | Hauler Hero encountered an unexpected error | Retry with backoff; if persistent, contact support |
- Integration questions: integrations@haulerhero.com
- API support: api-support@haulerhero.com