# Site API Integration Guide

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.

See the [Data Model](/site-data-model) page for the entity hierarchy and relationship rules.

## Prerequisites

You'll build and host this API on your own infrastructure, then share the URL and credentials with Hauler Hero.

- A public URL where the endpoint is reachable (e.g., `https://api.yourcompany.com/scale-hero/v1/sites`)
- An `API-KEY` that you issue to Hauler Hero. See [Authentication](/authentication).


## How it works

1. You implement `GET /scale-hero/v1/sites` on your infrastructure, following this specification.
2. You expose it at a public URL and issue an `API-KEY` to Hauler Hero.
3. Hauler Hero calls `GET /scale-hero/v1/sites?haulerId={haulerId}` with the `API-KEY` header.
4. You return all active sites, kiosks, and materials for that hauler.
5. Hauler Hero maps and stores the data for ongoing synchronization.


## Implementation requirements

Your implementation must:

- Accept a `haulerId` query parameter (UUID) identifying which hauler's data to return.
- Return **all active** sites, kiosks, and materials for that hauler.
- Include accurate `updatedAt` timestamps (ISO 8601) on every entity so Hauler Hero can track changes.
- Follow the required/optional fields defined in the **Schemas** section of the Site API reference.
- Authenticate requests via the `API-KEY` header.


## Request

`GET /scale-hero/v1/sites?haulerId={haulerId}`

| Parameter | In | Required | Notes |
|  --- | --- | --- | --- |
| `haulerId` | query | Yes | UUID identifying the hauler |
| `API-KEY` | header | Yes | The API key you issued to Hauler Hero |


See the **Schemas** section of the Site API reference for the exact `GetSitesResponse` shape you must return.

## Response codes

| Code | Error code | Meaning | When your implementation should return this |
|  --- | --- | --- | --- |
| `200` | — | Data returned successfully | Normal success with `sites`, `kiosks`, and `materials` arrays |
| `400` | `INVALID_PAYLOAD` | `haulerId` missing or malformed | The `haulerId` query parameter is absent or not a valid UUID |
| `401` | `UNAUTHORIZED` | API key invalid or missing | The `API-KEY` header is missing or doesn't match what you issued |
| `404` | `NOT_FOUND` | Hauler not found | No data exists in your system for the given `haulerId` |
| `500` | `INTERNAL_ERROR` | Unexpected error | Your system hit an unexpected error; log the incident for investigation |


## Support

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