Addresses
An address is a place plus a contact: who to collect from, or who to deliver to. Save it once and reuse its id in quotes and deliveries.
Create an address
POST /addresses
| Field | Type | Description |
|---|---|---|
name | string | required. Contact name. |
phone | string | required. Nigerian mobile number. The +234 and 0 forms are both accepted; it is returned in the 0XXXXXXXXXX form. |
email | string | Optional. |
address | string | required. The address as text, for example 23 Allen Avenue, Ikeja, Lagos. Include the area and state for the best match. |
place_id | string | Google place id, if you have one. |
latitude, longitude | number | If you have them, for example from your own map pin. |
notes | string | Directions or a landmark for the rider. |
metadata | object | Optional. Up to 20 string key/value pairs. |
curl https://api.getreeds.co/shipping/v1/addresses \
-H "Authorization: Bearer $REEDS_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Ada Okafor",
"phone": "08031234567",
"email": "ada@example.com",
"address": "23 Allen Avenue, Ikeja, Lagos"
}'
{
"status": "success",
"data": {
"id": "adr_7Hq2Lk9P",
"livemode": false,
"status": "verified",
"serviceable": true,
"contact": { "name": "Ada Okafor", "phone": "08031234567", "email": "ada@example.com" },
"submitted_address": "23 Allen Avenue, Ikeja, Lagos",
"location": {
"formatted_address": "23 Allen Ave, Ikeja, Lagos 101233, Nigeria",
"place_id": "ChIJ...",
"latitude": 6.6018,
"longitude": 3.3515,
"lga": "Ikeja",
"state": "Lagos",
"country": "NG"
},
"match": { "source": "text", "confidence": "exact" },
"suggestion": null,
"notes": null,
"metadata": {},
"created_at": "2026-10-26T10:15:00+01:00"
}
}
How Reeds resolves an address
Reeds works down this list and stops at the first rule that applies.
- With a
place_id. Reeds looks the place up. A precise place (a street address, a building or a business) isverified. A broad one, such as an area like Lekki or a whole road, isneeds_confirmation, because its pin is only the middle of that area. - With
latitudeandlongitude. The pin is trusted, and Reeds fills in the area and state from it. The address isverified. - From the text. Reeds geocodes it, restricted to Nigeria. An exact match (rooftop or street-number level, not a partial match) is
verified. An approximate match, or several candidates, isneeds_confirmationwith Reeds' best suggestion. No match isneeds_confirmationwith no suggestion.
If your system already validated the address, for example with a map pin or Google Places, send latitude and longitude, or the place_id of a precise place (a street address, building or business). You get a verified address without a confirmation step. A place id for an area or a whole road still needs confirmation.
Coverage and serviceable
Every resolved location is checked against the states Reeds serves. An address outside them is saved with serviceable: false and the reason ADDRESS_NOT_SERVICEABLE. It stays saved, but a quote that uses it returns available: false: with ADDRESS_NOT_SERVICEABLE, or with INTERSTATE_NOT_AVAILABLE when it is a drop-off in the FCT and the pickup is in Lagos. While an address is needs_confirmation, serviceable is null because there is no confirmed location to check. See Coverage.
No duplicates
Saving the same place with the same contact again, within one account, returns the existing address id instead of creating a duplicate. Addresses sent inline with a quote are never de-duplicated, so two merchants on one platform never share an address.
When an address needs confirmation
{
"status": "success",
"data": {
"id": "adr_3Mz8Rt1Q",
"status": "needs_confirmation",
"serviceable": null,
"submitted_address": "12 Church Street",
"location": null,
"match": { "source": "text", "confidence": "approximate" },
"suggestion": {
"formatted_address": "12 Church St, Ebute Metta, Lagos, Nigeria",
"place_id": "ChIJ...",
"latitude": 6.4853,
"longitude": 3.3816,
"lga": "Lagos Mainland",
"state": "Lagos"
}
}
}
This is a success, not an error. You can't quote an unconfirmed address, but you can create a draft with it.
Confirm an address
POST /addresses/{id}/confirm works only for addresses in needs_confirmation. Send one of three bodies:
| Body | Use it when |
|---|---|
{ "accept_suggestion": true } | Reeds' suggestion is right |
{ "place_id": "ChIJ..." } | You have the correct Google place id |
{ "latitude": 6.4853, "longitude": 3.3816 } | You have the exact pin |
curl https://api.getreeds.co/shipping/v1/addresses/adr_3Mz8Rt1Q/confirm \
-H "Authorization: Bearer $REEDS_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "accept_suggestion": true }'
The address becomes verified, and any drafts waiting on it move on. An address.confirmed webhook is sent.
Other address endpoints
| Endpoint | What it does |
|---|---|
GET /addresses | List addresses, filterable by status |
GET /addresses/{id} | Fetch one address |
PATCH /addresses/{id} | Change contact fields, notes and metadata. The location can't be edited: save a new address instead. A change never reaches deliveries already booked, because each delivery keeps a copy of its addresses taken at booking. |
DELETE /addresses/{id} | Delete a saved address and its contact details, for example when a receiver asks to be erased. Deliveries already booked keep their own copy. |
While a draft uses an address, DELETE is refused with 409 ADDRESS_IN_USE. Cancel the draft first. Deleting an address also expires its unused quotes at once, so booking one returns QUOTE_EXPIRED.
Personal data
Addresses hold receivers' names and phone numbers. Reeds processes them on your behalf, as the Nigeria Data Protection Act expects of a data processor, and your account agreement says so.
- Addresses sent inline with a quote that never became a delivery are deleted after 30 days.
- Saved addresses from
POST /addressesare your address book. They stay until you delete them withDELETE /addresses/{id}, which is also how you act on a receiver's request to be erased.