# Account API Integration Guide

The Account API creates and manages customer accounts, billing addresses, and primary contact information in Hauler Hero.

Use this API to create a new customer account record — either as part of onboarding a new customer or when synchronizing account data from another system.

## Prerequisites

- A `HERO-API-KEY` issued by Hauler Hero. See [Authentication](/authentication).
- Base URL: `https://api.haulerhero.com`


## Workflow

Account creation is a single call:

1. Build an account payload with at minimum `accountName`. Billing address and primary contact are optional but recommended for complete records.
2. Send `POST /hero-api/v1/accounts` with the payload and your `HERO-API-KEY` header.
3. Store the returned `accountId` and `accountNumber` — both are auto-generated by Hauler Hero and needed to reference the account in future API calls.


## Field requirements

Only `accountName` is required. All other fields are optional.

| Field | Required | Notes |
|  --- | --- | --- |
| `accountName` | Yes | 1–200 characters |
| `billingAddress.street` | No | Max 100 characters |
| `billingAddress.unit` | No | Max 20 characters |
| `billingAddress.city` | No | Max 50 characters |
| `billingAddress.state` | No | Two-letter US state code (e.g., `CA`, `NY`) |
| `billingAddress.country` | No | Max 50 characters |
| `billingAddress.zip` | No | US format: `12345` or `12345-6789` |
| `primaryContact.firstName` | No | Max 50 characters |
| `primaryContact.lastName` | No | Max 50 characters |
| `primaryContact.email` | No | Valid email format, max 100 characters |
| `primaryContact.phone` | No | Digits, spaces, parens, dashes, optional `+` prefix |


For full schema definitions see the **Schemas** section of the Account API reference.

## Response codes

| Code | Meaning | Action |
|  --- | --- | --- |
| `200` | Account created successfully | Store `accountId` and `accountNumber` for future reference |
| `400` | Invalid input | Check field formats — e.g., state must be two uppercase letters, zip must match US format |
| `401` | Unauthorized | Verify the `HERO-API-KEY` header is present and correct |
| `409` | Conflict — an account with this name already exists | Use the existing account or choose a distinct name |


## Support

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