# Scale API Integration Guide

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.

## Prerequisites

- A `HERO-API-KEY` issued by Hauler Hero. Each Hauler Hero account has a unique API key. See [Authentication](/authentication).
- Base URL: `https://api.haulerhero.com`


## Workflow

1. **Build the ticket payload** with site identification, at least one material, and optional inbound/outbound flow data.
2. **Send `POST /hero-api/v1/tickets`** with the payload and your `HERO-API-KEY` header. Call this endpoint every time a scale ticket is created or updated in your system.
3. **Store the returned `disposalTicketId`** — it's the Hauler Hero identifier for the ticket and is required to reference it later.
4. **Handle errors** per the response code table below.


## Required fields

| 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.

## Response codes

| 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 |


## Support

- Integration questions: [integrations@haulerhero.com](mailto:integrations@haulerhero.com)
- API support: [api-support@haulerhero.com](mailto:api-support@haulerhero.com)