HaulStow Developer API

The HaulStow Developer API lets your software talk to HaulStow. Your backend can ask for a price, create a delivery, check its status, and receive automatic status updates. You do not need to understand HaulStow’s internal systems. If you can send an HTTP request and read JSON, you can use this API.

This is a server-to-server API. Your frontend calls your backend, and your backend calls HaulStow. Never put a HaulStow API key in browser JavaScript, a mobile app, or a public repository.

What you need

Before you begin, get these from the HaulStow developer portal:

A developer application.
A test API key beginning with hsg_test_key_.
A tool for sending HTTP requests. The quickstart uses curl, which is already available on most macOS and Linux computers.

Start with the sandbox. It behaves like the live API but does not dispatch a rider, charge money, send messages, or create a real delivery.

Base URLs

Environment	Base URL	Credential
Sandbox (start here)	`https://sandbox.developer.haulstow.co/v1`	`hsg_test_key_...`
Live	`https://developer.haulstow.co/v1`	`hsg_live_key_...`

The URL and key must match. A live key cannot access sandbox data, and a test key cannot access live data. There is no environment field to add to your JSON.

The three ideas to remember

1. Put the key in the Authorization header

Authorization: Bearer hsg_test_key_your_key_here

Bearer is required, followed by one space and the complete API key.

2. Send an idempotency key when creating something

An idempotency key is a unique label for one action. It makes retrying safe if your network disconnects.

Idempotency-Key: order-1842-create

Reuse that value only when retrying the exact same request. Use a new value for a new recipient, address, delivery, or sandbox transition.

3. Read the `data` field

Every response has the same outer shape, called an envelope. On success, the useful result is inside data.

Response envelope

Success

{
  "success": true,
  "statusCode": 200,
    "message": "Delivery returned",
  "data": {
    "id": "dlv_3f1a821cdb58498cbb52f4706545a089",
    "status": "in_transit"
  }
}

Error

{
  "success": false,
  "statusCode": 422,
  "message": "Delivery request is invalid",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": {
      "fields": []
    }
  }
}

On failure, error.code is the short, stable value your program should check. message is the human-readable explanation. Every response also includes X-Request-ID. Save it in your logs. If you contact HaulStow support about a request, include this value so the request can be found quickly.

Common words

Word	Meaning
Application	The integration you create in the developer portal.
Recipient	The person receiving a package.
Address	A reusable drop-off location belonging to a recipient.
Delivery	One package movement from pickup to drop-off.
Sandbox	A safe test environment with simulated deliveries.
Webhook	An HTTP request HaulStow sends to your server when a delivery changes.
Scope	A permission attached to an API key, such as `deliveries:read`.

Start integrating

Follow the 10-minute quickstart to create a simulated delivery.
Read authentication before saving a key in your app.
Read idempotency before creating live deliveries.
Use webhooks for automatic updates, or polling as a simpler fallback while learning.
Open common errors when a request does not work.
Use the API reference when you need every field and status code.

Get started

Core concepts

Endpoint reference

What you need

Base URLs

The three ideas to remember

1. Put the key in the Authorization header

2. Send an idempotency key when creating something

3. Read the `data` field

Response envelope

Common words

Start integrating

​What you need

​Base URLs

​The three ideas to remember

​1. Put the key in the Authorization header

​2. Send an idempotency key when creating something

​3. Read the data field

​Response envelope

​Common words

​Start integrating

What you need

Base URLs

The three ideas to remember

1. Put the key in the Authorization header

2. Send an idempotency key when creating something

3. Read the `data` field

Response envelope

Common words

Start integrating