Customer API integration guide

Customer: Fernbank Logistics Sandbox connected Production keys pending Client-ready

How Fernbank Logistics' engineering team goes from sandbox keys to a live production integration with Relay API, with the code you need at each step. Prepared by your solutions engineer, Devon Marsh.

Sample template: the firm, people, clients and figures are fictional and shown for illustration only.

Get connected

Step 1: Authenticate

Exchange your client ID and secret for an access token. Tokens expire after 3600 seconds, so cache and refresh them rather than requesting a new one per call.

curl -X POST https://sandbox.relayapi.example/v2/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=fernbank_sandbox_8841" \
  -d "client_secret=REPLACE_WITH_YOUR_SECRET"

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Step 2: Call the shipments endpoint

import requests

headers = {"Authorization": "Bearer " + access_token}
resp = requests.get(
    "https://sandbox.relayapi.example/v2/shipments?status=in_transit",
    headers=headers,
)
print(resp.json())

Same request, your language

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://sandbox.relayapi.example/v2/shipments/SHP-88213"

resp = requests.get(
    f"{BASE_URL}/shipments/SHP-88213",
    headers={"Authorization": f"Bearer {access_token}"},
)
shipment = resp.json()

{
  "shipment_id": "SHP-88213",
  "status": "in_transit",
  "carrier": "Northline Freight",
  "eta": "2026-09-25T14:00:00Z",
  "origin": "Columbus, OH",
  "destination": "Reno, NV"
}

Core endpoints

Webhook flow for status updates

sequenceDiagram
    participant App as Fernbank app
    participant Relay as Relay API
    participant Carrier as Carrier network
    App->>Relay: POST /oauth/token (client credentials)
    Relay-->>App: access_token, expires_in 3600
    App->>Relay: POST /webhooks (register endpoint)
    Relay-->>App: 201 Created
    Carrier->>Relay: Status update (in transit to delivered)
    Relay->>App: POST to your webhook (signed payload)
    App-->>Relay: 200 OK within 5 seconds

Relay retries a webhook delivery up to 5 times with exponential backoff if your endpoint does not return a 200 within 5 seconds. Verify the X-Relay-Signature header on every payload before trusting it.

Common error codes

Go-live checklist

Next steps

1. Finish webhook signature verification and confirm it rejects unsigned payloads.
2. Book the technical review with Devon Marsh once the checklist is complete.
3. Run the load test and share results before the Oct 3 target go-live.