Skip to content
Sites/
Get Sites, Kiosks, and ma...

Site API (1.0.0)

The Site API manages sites, kiosks, and/or materials for the Hauler Hero platform.

Overview

This specification is designed for integration partners to implement on their platform. Once implemented, Hauler Hero will call this endpoint to retrieve and synchronize disposal sites, kiosks, and materials from your system.

Partner Implementation Requirements

  1. Implement the GET /scale-hero/v1/sites endpoint following this specification
  2. Expose the endpoint at a public URL (e.g., https://api.yourcompany.com/scale-hero/v1/sites)
  3. Provide API-KEY credentials to Hauler Hero
  4. Return all active sites, kiosks, and materials for the requested hauler
  5. Maintain accurate updatedAt timestamps for change tracking
  6. Follow the required/optional fields defined in the Schemas section below

How It Works

  1. Partner implements this API specification
  2. Partner provides endpoint URL and API-KEY to Hauler Hero
  3. Hauler Hero calls GET /scale-hero/v1/sites with the partner's haulerId
  4. Partner returns sites, kiosks, and materials in the specified format
  5. Hauler Hero maps and stores the data for ongoing synchronization

Data Model

See the Schemas section below for complete field definitions:

  • Site - Disposal site with address details (always required)
  • Kiosk - Kiosk/station linked to a site (optional - only if your system uses this concept)
  • Material - Material types with pricing at kiosks/sites

Important: Kiosk Concept is Optional

If your system uses kiosks (stations/points within a site):

  • Include the kiosks array in the response
  • Materials must have a kioskId to link them to a kiosk

If your system does not use kiosks:

  • Return an empty kiosks array or omit it
  • Materials must have a siteId to link them directly to a site

Note: Each material must have either a siteId OR/AND a kioskId, depending on your system's hierarchy.

Authentication

All requests require an API-KEY header for authentication.

Download OpenAPI description
site.json
site.yaml
Languages
Servers
Mock server
https://docs.haulerhero.com/_mock/site/
Production server
https://api.yourcompany.com/

Sites

Site, Kiosk, and Material management operations

Operations

Get Sites, Kiosks, and materials

Request

Retrieve all sites, kiosks, and materials for a specific hauler

Security
apiKey
Query
haulerIdstring(uuid)required

Unique identifier for the hauler

Example: haulerId=123e4567-e89b-12d3-a456-426614174000
curl -i -X GET \
  'https://docs.haulerhero.com/_mock/site/scale-hero/v1/sites?haulerId=123e4567-e89b-12d3-a456-426614174000' \
  -H 'API-KEY: YOUR_API_KEY_HERE'

Responses

Sites, kiosks, and materials retrieved successfully

Bodyapplication/json
successbooleanrequired

Whether the request was successful

Example: true
dataobject(SiteData)required
data.​sitesArray of objects(Site)

List of sites for the hauler

data.​kiosksArray of objects(Kiosk)

List of kiosks associated with the sites

data.​materialsArray of objects(Material)

List of materials available at the kiosks / sites

Response
application/json
{
  "success": true,
  "data": {
    "sites": [ … ],
    "kiosks": [ … ],
    "materials": [ … ]
  }
}