Skip to main content

TripCreateRequest

recipient_phonestring

A Ghana mobile number (0241234567 or +233241234567). The recipient gets texts with the tracking link and at key moments. Check sms in the response: queued, or off if texts aren't active.

sender_namestring

Your business name in the texts. Letters, digits, spaces and ' & - only.

Possible values: <= 30 characters

amount_to_collectnumber

What the courier should collect on delivery. Leave out if nothing is due.

Possible values: >= 0

currencystring
Default value: GHS
rider_refstring

Your own ID for the courier. Needed for cash balances.

Possible values: <= 64 characters

external_idstring

Your reference, e.g. an order number. Unique per account when set.

Possible values: <= 128 characters

destination objectrequired

One end of a route — supply exactly one of hex, plus_code, gps_code, point, or profile_slug.

gps_codestring

A GhanaPostGPS digital address, with or without dashes. It is looked up in the GhanaPostGPS registry and the route uses the centre of its cell. An unknown or malformed code returns 400 VALIDATION_ERROR.

Example: GA-183-8164
plus_codestring

A full Plus Code (Open Location Code), case-insensitive. The route uses the centre of its cell (about 14 m across for a 10-digit code). Short codes are rejected as ambiguous; expand them first with GET /v2/pluscode/{code}?ref=lat,lng.

Example: 6CQXJR37+F6
location_idstring

Physical location selector, mutually exclusive with hex/point/profile_slug. Private locations require a profile grant.

entrance_idstring

Canonical gate ID; requires profile_slug or location_id and excludes entrance_type.

entrance_revisioninteger

Reject if the approved revision changed.

Possible values: >= 1

profile_slugstring

Address-profile handle; access is checked before resolving coordinates/entrances

entrance_typestring

Optional explicit entrance for profile_slug. Otherwise defaults to truck/main gate selection, then profile point.

Possible values: [main, truck_gate, loading_dock, visitor, staff, pedestrian, compound]

hexstring

AfriHex code at resolution 7

Example: AF-GH-7-0GXTJJB0ZZZZZ
point object

Raw coordinate

lngnumber<double>
Example: -0.1867
latnumber<double>
Example: 5.604
headinginteger

Device compass bearing in degrees (0 = north). On dual-carriageway roads it disambiguates which carriageway the endpoint snaps to, so routes don't begin with a phantom U-turn. Omit when unknown.

Possible values: >= 0 and <= 359

Example: 270
destination_labelstring

Shown on the recipient's tracking page.

Possible values: <= 200 characters

modestring

Possible values: [motor_scooter, driving, bicycle, foot, truck]

Default value: motor_scooter
approaching_threshold_sinteger

trip.approaching fires when the ETA reaches this many seconds.

Possible values: >= 60 and <= 3600

Default value: 300
arrival_radius_minteger

Within this distance of the destination the courier has arrived.

Possible values: >= 20 and <= 1000

Default value: 100
scheduled_arrival_atstring<date-time>

Promised arrival; trip.delayed fires if the ETA runs more than 5 minutes past it.

expires_in_hoursinteger

Possible values: >= 1 and <= 72

Default value: 24
metadataobject

Your own data (up to 4 KB). Returned to you and in webhooks; never on the tracking page.

TripCreateRequest
{
"recipient_phone": "string",
"sender_name": "string",
"amount_to_collect": 0,
"currency": "GHS",
"rider_ref": "string",
"external_id": "string",
"destination": {
"gps_code": "GA-183-8164",
"plus_code": "6CQXJR37+F6",
"location_id": "string",
"entrance_id": "string",
"entrance_revision": 0,
"profile_slug": "string",
"entrance_type": "main",
"hex": "AF-GH-7-0GXTJJB0ZZZZZ",
"point": {
"lng": -0.1867,
"lat": 5.604
},
"heading": 270
},
"destination_label": "string",
"mode": "motor_scooter",
"approaching_threshold_s": 300,
"arrival_radius_m": 100,
"scheduled_arrival_at": "2024-07-29T15:51:28.071Z",
"expires_in_hours": 24,
"metadata": {}
}