HaulMatch
Documentation menu
Preview

API authentication and request identity

Create organization keys, choose scopes and make safe, repeatable API requests.

By HaulMatch · Updated

Integrations are in preview. Setup access depends on rollout and provider configuration. If your settings show integrations are not enabled, contact HaulMatch for availability. Contact us.

On this page

Create and protect a credential

Keys are organization-scoped and checked against their creator’s current membership. Revoked credentials and removed members lose access even when retrying an earlier request. To rotate a credential, create a replacement, update your server and revoke the previous connection.

  1. As organization owner, open Connections, name the connection and select the required scopes. A fleet owner can select a team to restrict the credential.
  2. Create the key and copy its secret once. Store it in your server’s secret manager or your automation tool’s credential store.
  3. Send Authorization: Bearer hm_org_... to your configured gateway under /api/integrations/v1. Replace YOUR_GATEWAY in the samples with the gateway origin provided for your integration environment.
Authenticated read (Shell)
curl 'https://YOUR_GATEWAY/api/integrations/v1/jobs' \
  -H 'Authorization: Bearer hm_org_REPLACE_WITH_KEY'

Choose the required scopes

ScopesPurpose
loads:read / loads:writeRead loads / create shipper organization loads.
quotes:read / quotes:write / quotes:acceptRead or preview quotes / submit, update or withdraw fleet quotes / award a shipper load.
jobs:read / jobs:writeRead jobs and external references / update authorized status or release an unfunded booking.
drivers:read / drivers:assignRead the permitted fleet directory / allocate an operating driver to company-pay work.
tracking:read / documents:read / payments:readRead authorized tracking, supported documents and payment state.
Scopes do not replace organization, team or job lifecycle checks. No machine credential can perform company money movements.

Make write requests repeatable

Every write requires Idempotency-Key: 8–120 printable characters. Generate and persist it in your source system before the first request, then reuse it for retries of that same request.

The same key with a different payload returns 409. A timeout can occur after a change committed, so inspect the outcome and retry with the original key. Do not generate a new key simply because the response was lost.

Write request headers (HTTP)
Authorization: Bearer hm_org_REPLACE_WITH_KEY
Content-Type: application/json
Idempotency-Key: 5d976b30-08c8-4a40-8892-f71cf6c8f242

Map external references

Load and quote creation can include externalRef. It is unique per connection and resource kind. Store both the HaulMatch ID and the partner reference in your source system.

Look up a reference with GET /references/LOAD/{externalRef} or GET /references/QUOTE/{externalRef}, URL-encoding its path value. Reusing an external reference with a new creation key returns 409 instead of creating another record.

Limits and errors

Job and quote lists are bounded at 100 items; the driver directory is bounded at 200. Marketplace load browsing supports page and limit. Inspect response schemas in the API reference before consuming lists.

Handle authentication, scope, validation and lifecycle errors explicitly. Retry transient failures with the original request key; investigate 409 conflicts rather than issuing a new creation request.