# Site API

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.


Version: 1.0.0

## Servers

Production server
```
https://api.yourcompany.com
```

## Security

### apiKey

API key for authenticating requests.

To obtain an API key:
- Contact your account manager
- Email: api-support@haulerhero.com

Include in request header: `API-KEY: your_api_key_here`


Type: apiKey
In: header
Name: API-KEY

## Download OpenAPI description

[Site API](https://docs.haulerhero.com/_bundle/site.yaml)

## Sites

Site, Kiosk, and Material management operations

### Get Sites, Kiosks, and materials

 - [GET /scale-hero/v1/sites](https://docs.haulerhero.com/site/sites/getsitedata.md): Retrieve all sites, kiosks, and materials for a specific hauler