{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Scale API Integration Guide"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"scale-api-integration-guide","__idx":0},"children":["Scale API Integration Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HERO-API-KEY"]}," issued by Hauler Hero. Each Hauler Hero account has a unique API key. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/authentication"},"children":["Authentication"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Base URL: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.haulerhero.com"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"workflow","__idx":2},"children":["Workflow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Build the ticket payload"]}," with site identification, at least one material, and optional inbound/outbound flow data."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /hero-api/v1/tickets"]}]}," with the payload and your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HERO-API-KEY"]}," header. Call this endpoint every time a scale ticket is created or updated in your system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store the returned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disposalTicketId"]}]}," — it's the Hauler Hero identifier for the ticket and is required to reference it later."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle errors"]}," per the response code table below."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"required-fields","__idx":3},"children":["Required fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Notes"},"children":["Notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID of the disposal site"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array with at least one item"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials[].id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID of the material"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials[].name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Material name (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"Paper\""]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials[].quantity"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Quantity as a number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials[].unitOfMeasure"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ton"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Gallon"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Pound"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Kilogram"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cubic Yard"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Cubic Meter"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Item"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials[].unitPriceCents"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unit price in cents (per the spec: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["15.50"]}," represents $0.155)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inboundFlow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide if the ticket has inbound flow data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inboundFlow.ticketNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inboundFlow"]}," is present"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your system's unique inbound ticket number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inboundFlow.updatedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inboundFlow"]}," is present"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outboundFlow"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Provide if the ticket has outbound flow data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outboundFlow.ticketNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outboundFlow"]}," is present"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your system's unique outbound ticket number"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outboundFlow.updatedAt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["outboundFlow"]}," is present"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 8601 timestamp"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customFields"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Map of string key/value pairs for integration-specific data (driver name, route, vehicle ID, customer reference, etc.)"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For full schema definitions and example payloads see the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Schemas"]}," section of the Scale API reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-codes","__idx":4},"children":["Response codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error code"},"children":["Error code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Action"},"children":["Action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["—"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ticket created successfully"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Store ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disposalTicketId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INVALID_PAYLOAD"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or malformed fields"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the field named in the error message and retry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["API key invalid or missing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HERO-API-KEY"]}," header is present and correct"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VALIDATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Business-rule violation (e.g., referenced material ID doesn't exist)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials[].id"]}," exist in Hauler Hero"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hauler Hero encountered an unexpected error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with backoff; if persistent, contact support"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":5},"children":["Support"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Integration questions: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:integrations@haulerhero.com"},"children":["integrations@haulerhero.com"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["API support: ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:api-support@haulerhero.com"},"children":["api-support@haulerhero.com"]}]}]}]},"headings":[{"value":"Scale API Integration Guide","id":"scale-api-integration-guide","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Workflow","id":"workflow","depth":2},{"value":"Required fields","id":"required-fields","depth":2},{"value":"Response codes","id":"response-codes","depth":2},{"value":"Support","id":"support","depth":2}],"frontmatter":{"seo":{"title":"Scale API Integration Guide"}},"lastModified":"2026-04-23T21:33:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/scale-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}