Harborline API integration guide

Engineers integrating an API at their desks

Integration guide Harborline Logistics RelayWorks

Owner: Omar Lewis. Updated Sep 24, 2026.

Environments

How Harborline's IT team connects the dispatch system to RelayWorks for the rollout, from sandbox keys to production. Prepared by Omar Lewis, who supports the integration through Wave 1.

Details
Sandbox base URLhttps://sandbox.relayworks.example/v1
Production base URLhttps://api.relayworks.example/v1
Auth methodOAuth 2.0 client credentials, 1 hour tokens
Rate limit300 requests per minute
Integration supportOmar Lewis, through Wave 1 go-live
TargetProduction keys before Wave 1, Nov 16

Get connected

✓Sandbox app created
SSO and SCIM confirmed
Dispatch reference lookup
Webhooks and go-live check
  • Sandbox app created: Client ID issued Sep 22
  • SSO and SCIM confirmed: Harborline IT, due Sep 30
  • Dispatch reference lookup: Read only, in sandbox
  • Webhooks and go-live check: Before Nov 16

Step 1: Authenticate

Exchange the client ID and secret for an access token at POST /oauth/token. Cache the token and refresh it before it expires rather than requesting one per call.

Step 2: Attach a dispatch reference to a handoff

Call POST /handoffs with the account, region, owner and the dispatch job reference. RelayWorks stores the reference only. It never writes back to dispatch.

Core endpoints

MethodEndpointPurposeScope
POST/oauth/tokenExchange credentials for an access tokennone
GET/handoffsList handoffs, filter by region, owner or statushandoffsread
POST/handoffsCreate a handoff with a dispatch job referencehandoffswrite
PATCH/handoffs/{id}Change owner or waiting reasonhandoffswrite
POST/webhooksRegister a webhook endpointwebhookswrite
GET/teamsRead teams synced from SCIMteamsread

Webhook flow for handoff updates

  • handoff.created when the service desk hands work to a region.
  • handoff.acknowledged when the receiving owner accepts it.
  • handoff.owner_changed on region transfers and the after hours duty manager fallback.

Webhooks retry for 24 hours with backoff. Verify the signature header on every call.

Common error codes

CodeMeaningWhat to do
401Token expired or invalidRefresh the token, then retry once
403Scope missing for this callAsk Omar to add the scope to your client
409Handoff already has an ownerUse PATCH to transfer ownership
429Rate limit reachedBack off and retry after the stated delay

Go-live checklist

Checklist
✓Sandbox client created
✓Token refresh tested
SCIM groups mapped to regional teams
Webhook signature verified
Dispatch reference lookup tested on 20 real jobs
Production keys issued after technical review

Production keys follow a technical review

Omar reviews the sandbox logs with Harborline IT before issuing production keys, so Wave 1 starts on a tested connection.

Next steps

  • Harborline IT confirms the identity provider and SCIM groups by Sep 30.
  • Omar schedules a 45 minute sandbox session for the week of Oct 5.
  • Production keys are issued after signature, before Nov 16.

Demo deal room. RelayWorks, Harborline Logistics, the people, prices and every figure are fictional sample data. Built on FuseBase.