Harborline API integration guide
Harborline API integration guide
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.
Get connected
- 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
| Method | Endpoint | Purpose | Scope |
|---|---|---|---|
| POST | /oauth/token | Exchange credentials for an access token | none |
| GET | /handoffs | List handoffs, filter by region, owner or status | handoffs |
| POST | /handoffs | Create a handoff with a dispatch job reference | handoffs |
| PATCH | /handoffs/{id} | Change owner or waiting reason | handoffs |
| POST | /webhooks | Register a webhook endpoint | webhooks |
| GET | /teams | Read teams synced from SCIM | teams |
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
| Code | Meaning | What to do |
|---|---|---|
| 401 | Token expired or invalid | Refresh the token, then retry once |
| 403 | Scope missing for this call | Ask Omar to add the scope to your client |
| 409 | Handoff already has an owner | Use PATCH to transfer ownership |
| 429 | Rate limit reached | Back off and retry after the stated delay |
Go-live checklist
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.