Road Ready NZ API

Staging and production are separate: each has its own keys, and an agency on staging exists only on staging. The switch at the top fills the base URL you choose into every example.

Create the key on your dashboard, under API Keys. It verifies Road Ready codes for your agency, and tests your own completion webhook if you have one. Send it on every call, in either header:

Checks the code a traveller gives you when they book. Verifying does not use the code up: you can verify the same code again, for example at booking and again at pickup.

Every call counts against your key, per calendar minute (UTC); counts start again at the start of each minute. A call over a limit is answered with 429 and a Retry-After header, the number of seconds until the next minute starts. The body names the limit in code, on the verify call as well: { "error": "Too many requests. Retry after 40 seconds.", "code": "rate_limited" }.

Who can have one:

• A booking platform, for all its agencies: one webhook per platform, with the platform key for the calls below.
• An agency with its own booking system and no booking platform: one webhook for that agency, with the agency's own key. An agency on a booking platform has none of its own; its events go to the platform's webhook, or nowhere if the platform has none.

Every event goes to one receiver only. The request, the signature and the rules below are the same for both.

It is sent only when the traveller opened the guide through a link that carried your booking reference as ref. A traveller who scans the QR poster or opens the short link has no ref, so nothing is sent for them: verify their code as before. The link may be the guide link or the agency's shortLink with ref added, and both take lang to choose the guide's language:

Staff can always verify a code by hand; the webhook does not replace that.

Ignore fields you do not know: we may add some.

Any 2xx means you have it; we do not read the response body. Anything else is a failed attempt and is sent again: 403, 503, every other 4xx and 5xx, a redirect (we do not follow redirects), no answer within 10 seconds, or a connection that fails. After a failed attempt we try again:

After 72 hours we stop, unless we send it again by hand after a problem on either side is fixed. Every repeat has the same eventId and the same body. The same booking may also be reported by two events with different codes, for example when two drivers of one booking each complete the guide.

One event is sent for each ref, whichever way the traveller comes to hold a code for that agency:

• they pass the quiz. The browser remembers the ref of the link for 30 days, so a traveller who opens it today and finishes the guide tomorrow in the same browser is still reported. The guide removes ref from the address once it has it, so do not expect to see it there;
• they already hold a valid code from another agency's guide, which then counts for this agency as well: the event is sent when they open your link;
• they already hold a valid code for this agency (a second booking with the same operator, or the email opened again): the event is sent when they open your link, with the code they hold. A ref we have reported is not reported again.

Once your webhook is set up, sends a test event to it, whenever you like, on staging and on production.

We then send the event like any other: the same body, signature, retries and time-out. Only these tell it apart:

Every test is a new event with its own eventId. While deliveries to you are paused (see Your answer and retries), a test event waits like any other: it shows pending with attempts: 0 until it is the hour's probe or the pause ends, so a fixed endpoint is found within the hour.

Both webhook calls also count against your rate limits. Errors are answered as { "error": "...", "code": "..." }: handle code; the wording of error can change.

Shows how the delivery of any of your events is going, a test or a real one. Add your Agency ID as agencyCode.

The answer never contains code or ref. An event that is not yours answers 404 event_not_found, the same as an unknown id.

Staging and production are separate: each has its own key, and an agency created on staging exists only on staging. The switch at the top fills the base URL you choose into every example.

We issue it when we set up your platform account. It works for every call on this tab, for every agency created with it. Send it on every call, in either header:

Creates the Road Ready agency of one of your operators.

• code identifies the agency in every other call, verify included. Store it next to your externalId.
• shortLink works as soon as the call returns. The QR poster is rendered in the background; see Read an agency and its poster.
• active is true; see Inactive agencies.

invalid_request, logo_invalid, logo_fetch_failed, agency_inactive (a repeat for an inactive agency), quota_exceeded (more new agencies in 24 hours than your daily limit). See Error codes.

Returns the same object as create. Poll it after a create or a logo change until the poster is ready: every 2 to 5 seconds, and stop after 2 minutes. It is normally ready within 60 seconds.

You can only read agencies created with your key. Any other code returns 404 with agency_not_found.

Lists the agencies of your platform account, newest first, for example to re-sync your database.

• Each agency is the same object as GET /partner/agencies/{code} returns.
• While more agencies exist, nextCursor is a string: pass it unchanged as cursor to get the next page. On the last page it is null. Treat it as opaque; its content can change.
• A platform account without agencies gets 200 OK with "agencies": [].
• To find the agency of one operator, GET /partner/agencies?externalId=op_1234 is quicker than paging.

invalid_request for a limit outside 1 to 100, or a cursor we did not issue to you.

Changes one or more fields of an agency and returns it as it is after the change (200 OK). code and shortLink never change, so QR codes already printed keep working.

Send at least one of them. Any other field (code, shortLink, externalId, ...) is refused with invalid_request.

invalid_request, logo_invalid and logo_fetch_failed (nothing is changed, the name included), agency_not_found (not one of your agencies), agency_inactive, contact_email_not_changeable. See Error codes.

For a poster whose qrStatus is failed, or one that has been pending for more than 5 minutes. No request body.

200 OK with the agency object and its current qrStatus:

• A poster that is pending and started less than 5 minutes ago is being rendered; the call changes nothing and answers pending.
• Any other poster, ready included, is rendered again and the call answers pending. Poll as after a create.

agency_not_found for a code that is not one of your agencies, agency_inactive for an inactive agency. See Error codes.

One platform key verifies the codes a traveller gives you for all your agencies. Send the agency's code from create as companyId. Verifying does not use the code up: you can verify the same code again, for example at booking and again at pickup.

Every call counts against your key, per calendar minute (UTC); counts start again at the start of each minute. A call over a limit is answered with 429 and a Retry-After header, the number of seconds until the next minute starts. The body names the limit in code, on the verify call as well: { "error": "Too many requests. Retry after 40 seconds.", "code": "rate_limited" }.

One key verifies for all your agencies, so failed verifications are counted for each agency (companyId) separately. Once one agency has used up its 10, verify calls for that agency answer 429, correct codes included, until the minute is over; your other agencies keep verifying. Wrong codes typed at one operator's counter therefore do not stop the others. Only when all your agencies together reach 60 failed verifications in a minute does every verify call with the key answer 429. A 429 looks the same in both cases; Retry-After is the time to wait for that agency, or for the key.

A verify call for a companyId that is not one of your agencies is answered with 401 and counts as a call without a valid key (30 a minute per IP address), not against an agency.

Creating and reading agencies are not held up by failed verifications, only by the 120 calls. A 429 from a create, change or poster retry is recorded under its X-Request-Id like every other one. It is separate from quota_exceeded, the daily limit of new agencies.

shortLink opens the guide in the language of the traveller's browser. To choose the language yourself, for example from the traveller's licence country, add lang to shortLink:

Instead of sending travellers to the short link, you can show the guide inside your own booking page. When the traveller finishes the quiz, the frame hands the Road Ready code to your page: the traveller copies, types or emails nothing. The frame's address is https://roadreadynz.com/embed/<code>?lang=<language>, with the agency's code.

See it working. Our demo booking page (staging) frames the guide, receives the code when the quiz is passed, confirms it and verifies it. The one-minute video shows it, then the same without a confirmation, where the traveller sees their code after 5 seconds.

Who can have one:

• A booking platform, for all its agencies: one webhook per platform, with the platform key for the calls below.
• An agency with its own booking system and no booking platform: one webhook for that agency, with the agency's own key. An agency on a booking platform has none of its own; its events go to the platform's webhook, or nowhere if the platform has none.

Every event goes to one receiver only. The request, the signature and the rules below are the same for both.

It is sent only when the traveller opened the guide through a link that carried your booking reference as ref. A traveller who scans the QR poster or opens the short link has no ref, so nothing is sent for them: verify their code as before. The link may be the guide link or the agency's shortLink with ref added, and both take lang to choose the guide's language:

Staff can always verify a code by hand; the webhook does not replace that.

Ignore fields you do not know: we may add some.

Any 2xx means you have it; we do not read the response body. Anything else is a failed attempt and is sent again: 403, 503, every other 4xx and 5xx, a redirect (we do not follow redirects), no answer within 10 seconds, or a connection that fails. After a failed attempt we try again:

After 72 hours we stop, unless we send it again by hand after a problem on either side is fixed. Every repeat has the same eventId and the same body. The same booking may also be reported by two events with different codes, for example when two drivers of one booking each complete the guide.

One event is sent for each ref, whichever way the traveller comes to hold a code for that agency:

• they pass the quiz. The browser remembers the ref of the link for 30 days, so a traveller who opens it today and finishes the guide tomorrow in the same browser is still reported. The guide removes ref from the address once it has it, so do not expect to see it there;
• they already hold a valid code from another agency's guide, which then counts for this agency as well: the event is sent when they open your link;
• they already hold a valid code for this agency (a second booking with the same operator, or the email opened again): the event is sent when they open your link, with the code they hold. A ref we have reported is not reported again.

Once your webhook is set up, sends a test event to it, whenever you like, on staging and on production.

We then send the event like any other: the same body, signature, retries and time-out. Only these tell it apart:

Every test is a new event with its own eventId. While deliveries to you are paused (see Your answer and retries), a test event waits like any other: it shows pending with attempts: 0 until it is the hour's probe or the pause ends, so a fixed endpoint is found within the hour.

Both webhook calls also count against your rate limits. Errors are answered as { "error": "...", "code": "..." }: handle code; the wording of error can change.

Shows how the delivery of any of your events is going, a test or a real one.

The answer never contains code or ref. An event that is not yours answers 404 event_not_found, the same as an unknown id.

Every call except verify answers errors as

Handle code; the wording of error can change. Verify keeps its own error bodies; see Verify a Road Ready code.

When an operator stops working with Road Ready, its agency is marked inactive; tell us if one of your operators leaves. An inactive agency:

• is still returned by read and list, with "active": false;
• cannot be changed: create (repeated with its externalId), change and poster retry return 409 with agency_inactive, and change nothing;
• keeps its code and externalId: neither is given to another agency;
• still verifies the Road Ready codes issued for it. Travellers who open its link still get the guide and a Road Ready code, but that code is not issued for the agency and does not verify for it.

We can make it active again on request; active is then true and everything works as before. Setting an agency to inactive through the API is not available yet.

• https on the default port, on a publicly reachable host. Redirects are followed up to three times and must meet the same rules.
• PNG, JPEG, WebP or GIF, checked by file content (not by the file name or Content-Type), 5 MB at most.
• A GIF is kept as a still image: its first frame, stored as PNG. An animated GIF does not animate on the poster. A GIF may have 8 megapixels at most (for example 2800 x 2800); a larger one, or the rare one whose PNG is larger than 5 MB, is answered with logo_invalid.
• The URL is fetched once, during create or change. Later changes to the file are not picked up; send the URL again with PATCH /partner/agencies/{code} to use a new version.