The HONK Connector lets an OutSystems app book and track towing and roadside-assistance

jobs with HONK without writing any HTTP, JSON, or custom code. HONK provides a REST API

for dispatching tow trucks and on-scene services (fuel, jump start, lockout, tire

change, winch-out, quick assist); this connector exposes its Jobs API as ready-to-use

ODC Server Actions.

Who it's for

Builders integrating ODC apps — insurance claims, motor clubs, fleet,

dealership, and roadside-assist apps — with HONK. It is a clone-and-own accelerator: it

wraps the HONK v3 Jobs API but is not a HONK account, does not store jobs, does not

receive HONK webhooks, and does not manage credentials. You bring the HONK API key, the

base URL (sandbox or production), and the app.

Key definitions

- Job — one request for roadside help: who needs it, what vehicle, where, and what

service. HONK finds and dispatches a service provider and tracks the job to completion.

- Job id — the unique id HONK assigns to a job (HonkJobStr.JobId). Keep it; you pass

it to every later call about that job.

- Service type — the kind of help: tow, fuel, jump, lockout, tire, winch, or

quick_assist.

- Job status — where the job is: PENDING, VERIFYING, SEARCHING, DISPATCHED, COMPLETE,

CANCELLED, or SCHEDULED.

- Dispatch — HONK assigning a provider to the job. Once DISPATCHED the job carries the

provider's name, phone, and an estimated arrival time.

- Progress milestones — the provider's checkpoints (en route, arrived, loaded

vehicle), returned in order on the job.

- Sandbox — HONK's test environment. It can automatically dispatch and progress test

jobs on a timer so you can exercise the whole lifecycle without a real tow.

How it works: configuration

The connector reads two Settings, configured in ODC Portal on the app that consumes

it:

- HonkBaseUrl — the HONK server. Defaults to the sandbox, https://api-sandbox.honkforhelp.com.

Production is https://api.honkforhelp.com.

- HonkApiKey — your HONK API key (a secret). It is sent as-is in the Authorization

header, with no "Bearer" prefix.

Enter the API key in Portal yourself. Never put it in source, a screenshot, or a chat.

How it works: errors

Every action returns Result (HonkResultStr). Check Result.Success first.

- Success True — the call worked. ErrorCode and ErrorMessage are empty and HttpStatus

is 200.

- ValidationFailed — your input broke a rule. ErrorMessage lists every violation;

HttpStatus is 0 and HONK was not called.

- BadRequest (HTTP 400) — HONK rejected the request, for example an invalid phone

number. ErrorMessage carries HONK's own error body.

- Unauthorized (HTTP 401 or 403) — the API key is missing, wrong, or not enabled for

the account.

- NotFound (HTTP 404) — for example an unknown job id.

- ProviderError — any other HTTP error from HONK.

- Timeout — the call did not finish in time (the REST client timeout is 30 seconds).

- Unexpected — anything else, such as a network failure. HttpStatus is 0.

For HTTP errors, ErrorMessage is HONK's raw response body. Match on ErrorCode, not on the

message text.

Actions

Every action returns Job (or JobPage) and Result.

- Honk_CreateJob — creates a job (POST /v3/jobs). Takes JobRequest; returns the new

Job, including its JobId and initial Status.

- Honk_GetJob — gets one job's current state (GET /v3/jobs/{jobId}). Takes JobId. Use

it to poll for status, provider, ETA, and progress.

- Honk_UpdateJob — updates a job (PUT /v3/jobs/{jobId}). Takes JobId and the full

desired JobRequest (PUT semantics: send everything, not just the changes).

- Honk_CancelJob — cancels a job (DELETE /v3/jobs/{jobId}). Takes JobId; returns the

cancelled Job with CancelledAt, CancelledBy, and CancelledAfterDispatch.

- Honk_ListJobs — lists jobs (GET /v3/jobs). Takes Filter (HonkJobFilterStr); returns

a JobPage with the jobs plus paging counters. Empty or zero filter fields are not sent.

Structures

- HonkJobRequestStr — what you send to create or update a job. Required: ReferenceNumber

(your own unique id for the job), ServiceType, CustomerFirstName, CustomerLastName,

CustomerPhone, Vehicle (as "Color Year Make Model"), and VehicleLocation. For a tow, also

DestinationLocation (unless NoDestinationTowStorageRequested). Optional: VIN, duty size,

accident details, an alternate point of contact, driver and agent notes, and a

JobDetails block of scene details.

- HonkLocationStr — a location: Latitude and Longitude, or an Address.

- HonkJobStr — the job HONK returns: JobId, Status, locations, EstimatedArrivalTime,

ProviderName, ProviderPhone, ProviderLocation, CustomerStatusUrl (safe to show the

motorist), EstimatedMileage, payment amounts in cents, cancellation details, Issues, and

Progress.

- HonkJobFilterStr — search and paging for Honk_ListJobs: date range, sort order,

Page and PerPage (1 to 100), a cursor (StartAtJobId), and matches on reference number,

customer id, phone, VIN, or free text.

- HonkJobPageStr — a page of jobs: Jobs, CurrentPage, PerPage, TotalEntries,

DataCount, and NextJobId (pass it back as StartAtJobId for the next page).

- HonkResultStr — Success, ErrorCode, ErrorMessage, HttpStatus.

- HonkJobDetailsStr, HonkJobIssueStr, HonkProgressStr — scene details, job

issues, and provider milestones.

End-to-end example: book a tow and follow it to completion

1. Build the request — fill a HonkJobRequestStr: ReferenceNumber (your claim or case

id), IsReadyToDispatch True, ServiceType "tow", the customer's name and phone, Vehicle,

VehicleLocation (latitude and longitude), DestinationLocation (the drop-off), and

VehicleInvolvedInAccident and RequiresWinchOut as they apply.

2. Create the job — call Honk_CreateJob. If Result.Success is False, show

Result.ErrorMessage (for ValidationFailed it lists exactly what to fix). Otherwise keep

Job.JobId and Job.CustomerStatusUrl.

3. Poll for status — on a timer, call Honk_GetJob with the JobId. When Status becomes

DISPATCHED, show ProviderName, ProviderPhone, and EstimatedArrivalTime. Progress shows

the provider's milestones as they happen. Stop polling at COMPLETE or CANCELLED.

4. Cancel if needed — call Honk_CancelJob. CancelledAfterDispatch tells you whether a

provider was already on the way.

5. Find jobs later — call Honk_ListJobs with Filter.ReferenceNumber set to your case id.

Because the connector does not receive HONK webhooks, status follows your polling cadence.

Pick an interval that fits how fresh the status needs to be.

Testing in the sandbox

Leave HonkBaseUrl on the sandbox. The sandbox can dispatch your job to a test provider

and move it through its states on a timer; you switch that on per job, because there is

no Setting for it. Set the sandbox fields on JobRequest.JobDetails:

SandboxAutoDispatch (True to auto-dispatch), SandboxAutoDispatchDelay,

SandboxAutoArriveVehicleLocationDelay, SandboxAutoArriveDestinationDelay,

SandboxAutoCompleteDelay (all in seconds), and SandboxEnableTextMessages. The connector sends these fields only when HonkBaseUrl contains "sandbox". Leave text

messages off unless you want the sandbox to send real texts to the customer phone. A job

with 10-second delays moves from VERIFYING to COMPLETE in about a minute. Never book a real

tow while testing: use a sandbox URL.

Scope and limitations

- Jobs API only (5 endpoints). Job notes, intermediate locations, documents, service

types, customer locations, referral codes, destinations, Visual IVR, and the jobEvents

webhook are not covered. CallbackUrl is accepted and validated (https only) and passed

through, but the connector has no webhook receiver.