Accept or decline offers
Receive offers for journeys and accept or decline them with a reason.
You will receive an offer for a journey, decide on it, and accept it (with a meeting point when one is required) or decline it with a reason. You need an API key and a webhook endpoint; offers are only sent to companies that work with the offer flow (see How a journey reaches you).
Step 1: Receive the offer
When Transferz offers you a journey, your endpoint receives
offerCreatedEvent. Its id is the offer id. The event carries the
route, the pickup time, the vehicle category, the add-ons, the fare you would be paid and the meeting
points you can choose from. Traveller names and contact details are left out until you accept.
{ "offerCreatedEvent": { "id": 6120044, "preferred": true, "fleet": { "fleetId": 3301, "fleetName": "Amsterdam airport fleet", "transferCompanyId": 2290, "transferCompanyName": "Canal City Transfers" }, "journey": { "id": 488213, "code": "TZ7K4Q-1", "pickUpTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "vehicleCategory": "SEDAN", "fareSummary": { "includingVat": 57.0, "excludingVat": 52.29, "vat": 4.71, "currency": "EUR" }, "travellerInfo": { "passengerCount": 2, "luggageCount": 2, "flightNumber": "TZ1234", "language": "en" } }, "meetingPoints": [ { "id": 2561, "title": "Schiphol Plaza meeting point", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" } ], "meetingPointRequired": true, "expiry": "2026-11-20T12:47:00", "status": "NOTIFIED", "replacement": false, "created": "2026-11-20T10:47:00.215" }}The example is shortened. Acknowledge the event with 2xx first and decide afterwards.
What the offer fields tell you:
| Field | Meaning |
|---|---|
id | The offer id. Use it to accept or decline. It is not the journey id. |
expiry | Accept or decline before this time. After it, the offer is EXPIRED. |
meetingPointRequired | When true, you must choose one of meetingPoints when you accept. |
preferred | true when your company is a preferred supplier for this journey. |
replacement | true when the journey is one you accepted before and has changed; see Replacement offers. |
journey.travellerInfo.driverComments | Requests from the traveller. Check you can meet them before you accept. |
Step 2: List open offers
If you missed an event, or want to check what is still open, list the offers you can still accept or decline:
/offers/available/allReferencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/offers/available/all' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'[ { "id": 6120044, "preferred": true, "fleet": { "fleetId": 3301, "fleetName": "Amsterdam airport fleet", "transferCompanyId": 2290, "transferCompanyName": "Canal City Transfers" }, "journey": { "id": 488213, "code": "TZ7K4Q-1", "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "vehicleCategory": "SEDAN", "fareSummary": { "includingVat": 57, "excludingVat": 52.29, "vat": 4.71, "currency": "EUR" } }, "meetingPoints": [ { "id": 2561, "title": "Schiphol Plaza meeting point", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" } ], "meetingPointRequired": true, "expiry": "2026-11-20T12:47:00", "status": "NOTIFIED", "replacement": false }]An empty list means nothing is open. To look at one offer, use
Get an offer with GET /offers/6120044.
Step 3: Accept the offer
Send the offer id in the path. When meetingPointRequired is true, send the id and type of one
of the offer's meetingPoints:
/offers/6120044/acceptReferencecurl --request POST \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/accept' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY' \ --data '{ "meetingPointId": 2561, "type": "HUB"}'{ "id": 488213, "code": "TZ7K4Q-1", "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "vehicleCategory": "SEDAN", "status": "CONFIRMED", "meetingPoint": { "id": 2561, "title": "Schiphol Plaza meeting point", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" }, "driverCode": "482KQM731", "assignmentStatus": "ASSIGNED", "travellerInfo": { "firstName": "Alex", "lastName": "Traveller", "email": "alex.traveller@example.com", "phone": "+447700900123", "passengerCount": 2 }}The response is the full journey, now including the traveller's details (shortened above).
assignmentStatus is ASSIGNED: the journey is yours. You also receive
journeyFleetAssignedEvent and
offerStatusChangedEvent with newStatus ACCEPTED. From here on,
use the journey id 488213, not the offer id.
When no meeting point is needed, send no body or an empty object. Do not send a meeting point for an inbound journey (from an address to a hub): it is refused.
Accepting an offer you already accepted succeeds again and returns the journey, so a retry after a timeout is safe.
Step 4: Or decline it
Give a reason. With OTHER, a description is required; with the other reasons it is optional
(up to 4,000 characters).
/offers/6120044/declineReferencecurl --request POST \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/offers/6120044/decline' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY' \ --data '{ "reason": "NO_VEHICLE_AVAILABILITY", "description": "All sedans are booked on 1 December in the afternoon."}'HTTP/1.1 204 No ContentThe reasons are listed in Constants. You receive
offerStatusChangedEvent with newStatus DECLINED.
Follow the offer's status
offerStatusChangedEvent tells you when an offer changes:
newStatus | What happened | What you do |
|---|---|---|
NOTIFIED | The offer was sent to you. | Decide before expiry. |
ACCEPTED | You accepted it. | Nothing; the journey arrives by journeyFleetAssignedEvent. |
DECLINED | You declined it. | Remove it from your list. |
EXPIRED | Nobody answered in time. | Remove it. |
MISSED | Another company accepted the journey first, or the journey was cancelled. | Remove it. |
{ "offerStatusChangedEvent": { "created": "2026-11-20T12:47:00.533", "offerId": 6120044, "journeyId": 488213, "transferCompanyId": 2290, "previousStatus": "NOTIFIED", "newStatus": "EXPIRED" }}Replacement offers
When a journey you accepted changes, Transferz can offer it to you again as a replacement offer:
replacement is true and the journey id is the one you already have. Read the changed details
and accept or decline it as usual.
- Accept to keep the journey with its new details.
- Decline and the journey is taken away from you: you receive
journeyFleetUnassignedEvent.
Errors
| Status | Code | Cause | What to do |
|---|---|---|---|
400 | OFFER_MISSED | Another company accepted the journey first. | Remove the offer. |
400 | OFFER_EXPIRED | The offer passed its expiry. | Remove the offer; answer offers sooner. |
400 | OFFER_FINALIZED | You already declined the offer, or you try to decline an offer that is accepted, expired or missed. | Check the offer with Get an offer. |
400 | INVALID_MEETING_POINT | A meeting point is required and none was sent, or the id is not one of the offer's meeting points. | Send the id and type of one of meetingPoints. |
400 | INBOUND_JOURNEY_MEETING_POINT | A meeting point was sent for an inbound journey. | Accept without a body. |
400 | DECLINE_DESCRIPTION_MISSED | The reason OTHER was sent without a description. | Add a description. |
403 | INSUFFICIENT_PERMISSIONS | The offer is for another company. | Check the offer id. |
404 | — | No offer with this id (empty body). | Check the offer id and the environment. |
The error format is described in Errors.
Related
Walk-through