Job Submission API

The Carrier Hub provides a simple REST API that allows any third-party platform -- including eBay stores, Shopify merchants, WooCommerce shops, and custom order management systems -- to submit delivery jobs directly into available loads. Matched carriers can then bid on and fulfil your deliveries.

REST / JSON API Key Auth Instant Load Posting

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. Generate your API key from the Shipper Portal → API Keys page.

Authorization: Bearer chk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep your API key secret. Never expose it in client-side code or public repositories. Revoke and regenerate immediately if compromised.

Submit a Delivery Job

POST/api/v1/jobs

Creates a new delivery job on the platform. The job will be visible to all verified carriers and can receive bids immediately.

Request Body (JSON)

Field	Type	Required	Description
title	string	Required	Short description of the delivery (max 200 chars)
pickupAddress	string	Required	Full collection address including postcode
deliveryAddress	string	Required	Full delivery address including postcode
pickupDate	string (ISO 8601)	Required	Requested collection date/time, e.g. 2026-04-01T09:00:00Z
weight	number	Optional	Total weight in kg
length	number	Optional	Package length in cm
width	number	Optional	Package width in cm
height	number	Optional	Package height in cm
description	string	Optional	Additional notes for the carrier (max 1000 chars)
externalOrderRef	string	Optional	Your internal order reference (e.g. eBay order ID, Shopify order number)
budgetMin	number	Optional	Minimum acceptable bid in GBP
budgetMax	number	Optional	Maximum acceptable bid in GBP
vehicleType	string	Optional	Preferred vehicle: van, luton, artic, flatbed, refrigerated
isFragile	boolean	Optional	Mark as fragile (default: false)
requiresTailLift	boolean	Optional	Tail lift required (default: false)

Example Request

cURL

curl -X POST https://www.thecarrierhub.com/api/v1/jobs \
  -H "Authorization: Bearer chk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "eBay parcel -- Manchester to London",
    "pickupAddress": "45 Deansgate, Manchester, M3 2AY",
    "deliveryAddress": "10 Downing Street, London, SW1A 2AA",
    "pickupDate": "2026-04-01T09:00:00Z",
    "weight": 5.2,
    "externalOrderRef": "EB-293847561",
    "description": "Fragile electronics, handle with care",
    "isFragile": true
  }'

Node.js Example

JavaScript / Node.js

const response = await fetch('https://www.thecarrierhub.com/api/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer chk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Shopify order #1234 -- Birmingham to Leeds',
    pickupAddress: '1 New Street, Birmingham, B2 4QA',
    deliveryAddress: '5 Briggate, Leeds, LS1 6HD',
    pickupDate: '2026-04-02T10:00:00Z',
    weight: 3.5,
    externalOrderRef: 'SHOP-1234',
  }),
});

const data = await response.json();
console.log(data.jobId); // Use this to track the job

Python Example

Python (requests)

import requests

response = requests.post(
    'https://www.thecarrierhub.com/api/v1/jobs',
    headers={
        'Authorization': 'Bearer chk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={
        'title': 'WooCommerce order -- Bristol to Cardiff',
        'pickupAddress': '1 Corn Street, Bristol, BS1 1HT',
        'deliveryAddress': '5 St Mary Street, Cardiff, CF10 1AT',
        'pickupDate': '2026-04-03T08:00:00Z',
        'weight': 12.0,
        'externalOrderRef': 'WC-5678',
    }
)

data = response.json()
print(data['jobId'])

Success Response (201 Created)

{
  "success": true,
  "jobId": 1042,
  "externalOrderRef": "EB-293847561",
  "message": "Job posted successfully"
}

Error Codes

HTTP Status	Code	Description
201	--	Job created successfully
400	VALIDATION_ERROR	Missing or invalid fields in the request body
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key has been revoked
429	RATE_LIMITED	Too many requests -- maximum 100 jobs per minute
500	INTERNAL_ERROR	Server error -- contact support if persistent

Rate Limits

The API is rate-limited to 100 requests per minute per API key. If you exceed this limit, you will receive a 429 Too Many Requests response. Implement exponential backoff in your integration to handle this gracefully.