{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Site API Integration Guide"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"site-api-integration-guide","__idx":0},"children":["Site API Integration Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Site API is implemented by integration partners on their own infrastructure. Once implemented, Hauler Hero calls the partner's endpoint to retrieve and synchronize disposal sites, kiosks, and materials for a given hauler."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/site-data-model"},"children":["Data Model"]}," page for the entity hierarchy and relationship rules."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You'll build and host this API on your own infrastructure, then share the URL and credentials with Hauler Hero."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A public URL where the endpoint is reachable (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.yourcompany.com/scale-hero/v1/sites"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-KEY"]}," that you issue to Hauler Hero. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/authentication"},"children":["Authentication"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":2},"children":["How it works"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You implement ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /scale-hero/v1/sites"]}," on your infrastructure, following this specification."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You expose it at a public URL and issue an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-KEY"]}," to Hauler Hero."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Hauler Hero calls ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /scale-hero/v1/sites?haulerId={haulerId}"]}," with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-KEY"]}," header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You return all active sites, kiosks, and materials for that hauler."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Hauler Hero maps and stores the data for ongoing synchronization."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation-requirements","__idx":3},"children":["Implementation requirements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your implementation must:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Accept a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["haulerId"]}," query parameter (UUID) identifying which hauler's data to return."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Return ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["all active"]}," sites, kiosks, and materials for that hauler."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include accurate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updatedAt"]}," timestamps (ISO 8601) on every entity so Hauler Hero can track changes."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Follow the required/optional fields defined in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Schemas"]}," section of the Site API reference."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Authenticate requests via the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-KEY"]}," header."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request","__idx":4},"children":["Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /scale-hero/v1/sites?haulerId={haulerId}"]}]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"In"},"children":["In"]},{"$$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":["haulerId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["query"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID identifying the hauler"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-KEY"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["header"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The API key you issued to Hauler Hero"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Schemas"]}," section of the Site API reference for the exact ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetSitesResponse"]}," shape you must return."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"response-codes","__idx":5},"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":"When your implementation should return this"},"children":["When your implementation should return this"]}]}]},{"$$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":["Data returned successfully"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Normal success with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sites"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kiosks"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["materials"]}," arrays"]}]},{"$$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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["haulerId"]}," missing or malformed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["haulerId"]}," query parameter is absent or not a valid UUID"]}]},{"$$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":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["API-KEY"]}," header is missing or doesn't match what you issued"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Hauler not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No data exists in your system for the given ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["haulerId"]}]}]},{"$$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":["Unexpected error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Your system hit an unexpected error; log the incident for investigation"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":6},"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":"Site API Integration Guide","id":"site-api-integration-guide","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Implementation requirements","id":"implementation-requirements","depth":2},{"value":"Request","id":"request","depth":2},{"value":"Response codes","id":"response-codes","depth":2},{"value":"Support","id":"support","depth":2}],"frontmatter":{"seo":{"title":"Site API Integration Guide"}},"lastModified":"2026-04-23T21:36:52.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/site-integration","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}