Preview

Organization API reference

Browse the current REST endpoints, required scopes, parameters, request schemas and responses.

By HaulMatch · Updated 9 October 2026

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

API basics
REST endpoints
Shared schemas

API basics

All endpoints below are relative to your configured gateway’s /api/integrations/v1 base. Use an owner-issued organization Bearer key; every write requires a stable Idempotency-Key.

The reference is rendered from the downloadable OpenAPI specification. Schemas describe the published contract; broad response objects intentionally allow additional fields. Machine keys cannot move company money.

REST endpoints

Contract version 1.0.0. Paths are relative to /api/integrations/v1.

GET

/loads

Organization loads for a shipper; public available loads for a fleet

Required scope: loads:read

Parameters
Name	Location	Required	Type and details
page	query	No	integer; minimum 1
limit	query	No	integer; minimum 1; maximum 100

Responses

200Success; list responses are bounded

View get /loads 200 application/json schema

GET /loads 200 application/json schema

{
  "oneOf": [
    {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    {
      "type": "object",
      "additionalProperties": true
    }
  ],
  "description": "Shippers receive their organization loads as an array. Fleets receive a paginated marketplace result."
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/loads

Create a shipper organization load

Required scope: loads:write

Parameters
Name	Location	Required	Type and details
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Request body (required)

application/json

Schema: CreateLoad

View post /loads request schema

POST /loads request schema

{
  "$ref": "#/components/schemas/CreateLoad"
}

Responses

200Success; list responses are bounded

View post /loads 200 application/json schema

POST /loads 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/quotes

List shipper load quotes or this fleet’s quotes

Required scope: quotes:read

Parameters
Name	Location	Required	Type and details
jobId	query	No	string — Required for shippers; optional for fleets

Responses

200Success; list responses are bounded

View get /quotes 200 application/json schema

GET /quotes 200 application/json schema

{
  "type": "array",
  "items": {
    "type": "object",
    "additionalProperties": true
  }
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/quotes

Submit a fleet quote with explicit payout ownership

Required scope: quotes:write

Parameters
Name	Location	Required	Type and details
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Request body (required)

application/json

Schema: CreateQuote

View post /quotes request schema

POST /quotes request schema

{
  "$ref": "#/components/schemas/CreateQuote"
}

Responses

200Success; list responses are bounded

View post /quotes 200 application/json schema

POST /quotes 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/quotes/{quoteId}/update

Update a pending fleet quote

Required scope: quotes:write

Parameters
Name	Location	Required	Type and details
quoteId	path	Yes	string
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Request body (required)

application/json

Schema: UpdateQuote

View post /quotes/{quoteid}/update request schema

POST /quotes/{quoteId}/update request schema

{
  "$ref": "#/components/schemas/UpdateQuote"
}

Responses

200Success; list responses are bounded

View post /quotes/{quoteid}/update 200 application/json schema

POST /quotes/{quoteId}/update 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/quotes/{quoteId}/withdraw

Withdraw a pending fleet quote

Required scope: quotes:write

Parameters
Name	Location	Required	Type and details
quoteId	path	Yes	string
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Responses

200Success; list responses are bounded

View post /quotes/{quoteid}/withdraw 200 application/json schema

POST /quotes/{quoteId}/withdraw 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/quotes/{quoteId}/accept

Award a shipper organization load

Required scope: quotes:accept

Parameters
Name	Location	Required	Type and details
quoteId	path	Yes	string
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Request body (required)

application/json

View post /quotes/{quoteid}/accept request schema

POST /quotes/{quoteId}/accept request schema

{
  "type": "object",
  "properties": {
    "acknowledgeUnverifiedRisk": {
      "type": "boolean"
    }
  }
}

Responses

200Success; list responses are bounded

View post /quotes/{quoteid}/accept 200 application/json schema

POST /quotes/{quoteId}/accept 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/jobs

List organization jobs; fleet keys see their assigned team

Required scope: jobs:read

Responses

200Success; list responses are bounded

View get /jobs 200 application/json schema

GET /jobs 200 application/json schema

{
  "type": "array",
  "items": {
    "type": "object",
    "additionalProperties": true
  }
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/jobs/{jobId}

Get an organization job and authorized quotes

Required scope: jobs:read

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string

Responses

200Success; list responses are bounded

View get /jobs/{jobid} 200 application/json schema

GET /jobs/{jobId} 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/jobs/{jobId}/release-booking

Release an unfunded booking and relist its load

Required scope: jobs:write

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Responses

200Success; list responses are bounded

View post /jobs/{jobid}/release-booking 200 application/json schema

POST /jobs/{jobId}/release-booking 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/jobs/{jobId}/status

Update an authorized job’s delivery state

Required scope: jobs:write

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Request body (required)

application/json

View post /jobs/{jobid}/status request schema

POST /jobs/{jobId}/status request schema

{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "IN_TRANSIT",
        "COMPLETED",
        "CANCELLED"
      ]
    }
  }
}

Responses

200Success; list responses are bounded

View post /jobs/{jobid}/status 200 application/json schema

POST /jobs/{jobId}/status 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

POST

/jobs/{jobId}/driver

Allocate a verified operating driver to a COMPANY-pay job before transit

Required scope: drivers:assign

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string
Idempotency-Key	header	Yes	string; minimum length 8; maximum length 120

Request body (required)

application/json

View post /jobs/{jobid}/driver request schema

POST /jobs/{jobId}/driver request schema

{
  "type": "object",
  "required": [
    "driverId"
  ],
  "properties": {
    "driverId": {
      "type": "string",
      "description": ""
    },
    "teamId": {
      "type": "string",
      "description": ""
    }
  }
}

Responses

200Success; list responses are bounded

View post /jobs/{jobid}/driver 200 application/json schema

POST /jobs/{jobId}/driver 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/drivers

List fleet member drivers within the key’s team restriction

Required scope: drivers:read

Responses

200Success; list responses are bounded

View get /drivers 200 application/json schema

GET /drivers 200 application/json schema

{
  "type": "array",
  "items": {
    "type": "object",
    "additionalProperties": true
  }
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/jobs/{jobId}/tracking

Get tracking for an organization job

Required scope: tracking:read

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string

Responses

200Success; list responses are bounded

View get /jobs/{jobid}/tracking 200 application/json schema

GET /jobs/{jobId}/tracking 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/jobs/{jobId}/payment

Read the job’s milestone payment and ledger

Required scope: payments:read

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string

Responses

200Success; list responses are bounded

View get /jobs/{jobid}/payment 200 application/json schema

GET /jobs/{jobId}/payment 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/jobs/{jobId}/documents/{type}

Generate an authorized PDF; response contains filename, contentType and base64

Required scope: documents:read

Parameters
Name	Location	Required	Type and details
jobId	path	Yes	string
type	path	Yes	string

Responses

200Success; list responses are bounded

View get /jobs/{jobid}/documents/{type} 200 application/json schema

GET /jobs/{jobId}/documents/{type} 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/references/{kind}/{externalRef}

Look up a tenant-authorized partner reference (LOAD or QUOTE)

Required scope: jobs:read

Parameters
Name	Location	Required	Type and details
kind	path	Yes	string
externalRef	path	Yes	string

Responses

200Success; list responses are bounded

View get /references/{kind}/{externalref} 200 application/json schema

GET /references/{kind}/{externalRef} 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

GET

/quotes/{quoteId}/preview

Preview shipper freight, GST, fees and total before awarding a quote

Required scope: quotes:read

Parameters
Name	Location	Required	Type and details
quoteId	path	Yes	string

Responses

200Success; list responses are bounded

View get /quotes/{quoteid}/preview 200 application/json schema

GET /quotes/{quoteId}/preview 200 application/json schema

{
  "type": "object",
  "additionalProperties": true
}

400Payload validation failed

401Missing organization key

403Scope, organization, team or current membership denied

404Resource not found

409Idempotency, external-reference or lifecycle conflict

429A shared organisation, key or endpoint quota was reached. Respect Retry-After.

503Shared limits or the service are unavailable. Sensitive requests fail closed; respect Retry-After.

Shared schemas

LoadData

Required fields: pickupLocation, dropoffLocation, loadType, itemName, readiness

LoadData schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "pickupLocation",
    "dropoffLocation",
    "loadType",
    "itemName",
    "readiness"
  ],
  "properties": {
    "pickupLocation": {
      "type": "string",
      "description": "Pickup address, minimum 3 characters",
      "minLength": 3
    },
    "pickupLat": {
      "type": "number",
      "description": "",
      "minimum": -90,
      "maximum": 90
    },
    "pickupLng": {
      "type": "number",
      "description": "",
      "minimum": -180,
      "maximum": 180
    },
    "pickupOsmLat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "pickupOsmLng": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "pickupGeoProvider": {
      "type": "string",
      "enum": [
        "GOOGLE",
        "OSM",
        "MANUAL",
        "INTERNAL"
      ]
    },
    "pickupPlaceId": {
      "type": "string"
    },
    "dropoffLocation": {
      "type": "string",
      "description": "Delivery address, minimum 3 characters",
      "minLength": 3
    },
    "dropoffLat": {
      "type": "number",
      "description": "",
      "minimum": -90,
      "maximum": 90
    },
    "dropoffLng": {
      "type": "number",
      "description": "",
      "minimum": -180,
      "maximum": 180
    },
    "dropoffOsmLat": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "dropoffOsmLng": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    },
    "dropoffGeoProvider": {
      "type": "string",
      "enum": [
        "GOOGLE",
        "OSM",
        "MANUAL",
        "INTERNAL"
      ]
    },
    "dropoffPlaceId": {
      "type": "string"
    },
    "loadType": {
      "type": "string",
      "description": "Freight category"
    },
    "itemName": {
      "type": "string",
      "description": "Load title",
      "minLength": 2
    },
    "readiness": {
      "type": "string",
      "enum": [
        "READY_NOW",
        "URGENT",
        "AVAILABLE_FROM",
        "ESTIMATE_ONLY"
      ]
    },
    "availableFromDate": {
      "type": "string",
      "description": "ISO 8601 date or date-time"
    },
    "loadWeight": {
      "type": "number",
      "description": "Total weight in kg",
      "minimum": 0
    },
    "quantity": {
      "type": "integer",
      "minimum": 1
    },
    "itemLength": {
      "type": "number",
      "description": "Metres",
      "minimum": 0
    },
    "itemWidth": {
      "type": "number",
      "description": "Metres",
      "minimum": 0
    },
    "itemHeight": {
      "type": "number",
      "description": "Metres",
      "minimum": 0
    },
    "weightEach": {
      "type": "number",
      "description": "Weight per item in kg",
      "minimum": 0
    },
    "hasDelicateItems": {
      "type": "boolean"
    },
    "needsBlanketWrap": {
      "type": "boolean"
    },
    "needsAssemblyAssist": {
      "type": "boolean"
    },
    "isDriveable": {
      "type": "boolean"
    },
    "isNew": {
      "type": "boolean"
    },
    "needsCovered": {
      "type": "boolean"
    },
    "isEmpty": {
      "type": "boolean"
    },
    "atInternationalPort": {
      "type": "boolean"
    },
    "requiresContainerHire": {
      "type": "boolean"
    },
    "isRegistered": {
      "type": "boolean"
    },
    "hasDangerousGoods": {
      "type": "boolean"
    },
    "contentsSecured": {
      "type": "boolean"
    },
    "pipeMaterial": {
      "type": "string"
    },
    "needsBolsters": {
      "type": "boolean"
    },
    "pipePackaging": {
      "type": "string"
    },
    "isPalletised": {
      "type": "boolean"
    },
    "temperatureC": {
      "type": "number"
    },
    "hayPackaging": {
      "type": "string"
    },
    "needsMoistureProtection": {
      "type": "boolean"
    },
    "hayType": {
      "type": "string"
    },
    "needsTippingTrailer": {
      "type": "boolean"
    },
    "pickupSiteType": {
      "type": "string"
    },
    "pickupFacilities": {
      "type": "string"
    },
    "pickupNotes": {
      "type": "string"
    },
    "pickupContactName": {
      "type": "string"
    },
    "pickupContactPhone": {
      "type": "string"
    },
    "dropoffSiteType": {
      "type": "string"
    },
    "dropoffFacilities": {
      "type": "string"
    },
    "dropoffNotes": {
      "type": "string"
    },
    "dropoffContactName": {
      "type": "string"
    },
    "dropoffContactPhone": {
      "type": "string"
    },
    "budget": {
      "type": "number",
      "description": "Optional AUD target price",
      "minimum": 0
    },
    "budgetPublished": {
      "type": "boolean"
    },
    "requiredDate": {
      "type": "string",
      "description": "ISO 8601 date or date-time"
    },
    "details": {
      "type": "string",
      "description": "Equipment, time windows and freight instructions"
    },
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

QuoteData

Required fields: jobId, amount

QuoteData schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "jobId",
    "amount"
  ],
  "properties": {
    "jobId": {
      "type": "string",
      "description": ""
    },
    "amount": {
      "type": "number",
      "minimum": 0.01,
      "description": "AUD, excluding GST, at most two decimal places"
    },
    "baseRate": {
      "type": "number",
      "description": "",
      "minimum": 0
    },
    "distanceFee": {
      "type": "number",
      "description": "",
      "minimum": 0
    },
    "laborFee": {
      "type": "number",
      "description": "",
      "minimum": 0
    },
    "conditions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "expectedDriverReceivesCents": {
      "type": "integer"
    },
    "message": {
      "type": "string",
      "description": ""
    },
    "pickupPlan": {
      "type": "string",
      "description": "",
      "minLength": 2,
      "maxLength": 160
    },
    "deliveryPlan": {
      "type": "string",
      "description": "",
      "minLength": 2,
      "maxLength": 160
    },
    "vehicleEquipment": {
      "type": "string",
      "description": "",
      "minLength": 2,
      "maxLength": 160
    },
    "bundleId": {
      "type": "string"
    }
  }
}

CreateLoad

Required fields: data

CreateLoad schema

{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/LoadData"
    },
    "externalRef": {
      "type": "string",
      "maxLength": 160
    }
  }
}

CreateQuote

Required fields: data, payoutMode

CreateQuote schema

{
  "type": "object",
  "required": [
    "data",
    "payoutMode"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/QuoteData"
    },
    "payoutMode": {
      "type": "string",
      "enum": [
        "DRIVER",
        "COMPANY"
      ]
    },
    "driverId": {
      "type": "string",
      "description": "Required for DRIVER mode; current fleet member"
    },
    "teamId": {
      "type": "string",
      "description": "Ignored in favour of a key’s fixed team restriction"
    },
    "externalRef": {
      "type": "string",
      "maxLength": 160
    }
  }
}

Error

Error schema

{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer"
    },
    "message": {
      "type": "string",
      "description": ""
    }
  }
}

WebhookEvent

Required fields: id, type, createdAt, organizationId, data

WebhookEvent schema

{
  "type": "object",
  "required": [
    "id",
    "type",
    "createdAt",
    "organizationId",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": ""
    },
    "type": {
      "type": "string",
      "description": ""
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "organizationId": {
      "type": "string",
      "description": ""
    },
    "teamId": {
      "type": "string",
      "nullable": true
    },
    "data": {
      "type": "object",
      "additionalProperties": true
    }
  }
}

UpdateQuote

Required fields: amount

UpdateQuote schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "amount"
  ],
  "properties": {
    "amount": {
      "type": "number",
      "minimum": 0.01
    },
    "baseRate": {
      "type": "number",
      "minimum": 0
    },
    "distanceFee": {
      "type": "number",
      "minimum": 0
    },
    "laborFee": {
      "type": "number",
      "minimum": 0
    },
    "conditions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "expectedDriverReceivesCents": {
      "type": "integer"
    },
    "message": {
      "type": "string"
    },
    "pickupPlan": {
      "type": "string",
      "minLength": 2,
      "maxLength": 160
    },
    "deliveryPlan": {
      "type": "string",
      "minLength": 2,
      "maxLength": 160
    },
    "vehicleEquipment": {
      "type": "string",
      "minLength": 2,
      "maxLength": 160
    },
    "bundleId": {
      "type": "string"
    }
  }
}

For request examples and retry behavior, read API authentication.