Contacts

Your address book in one list: saved recipients (ben_…), your pickup places (plc_…, your stores and warehouses, to choose a delivery's pickup from with pickupPlaceId) and customers (cus_…, everyone your deliveries went to, kept from the deliveries). The older lists (/places, /customers, and /beneficiaries and /addresses) answer the same records and stay as deprecated aliases.

On this page

Your address book (recipients, pickup places and customers)
Save a recipient or add a pickup place
Your own addresses first while a stop is typed
Get a contact
Edit a recipient or a pickup place
Delete a contact (a customer is forgotten with their addresses)
A contact's addresses

Note:

Send your key as key=YOUR_API_KEY on the address, or in the X-NWays-Api-Key header. API keys

Base address: https://nways.ng/maps/v1/fleet

Your address book (recipients, pickup places and customers)

GET https://nways.ng/maps/v1/fleet/contacts

One kind (kind=recipient|place|customer, each in its own order and pages), or all of them: your pickup places (the default first), then your saved recipients (by name, up to limit), then your customers (most recent delivery first, a page at a time: nextPageToken goes on through the customers only). q finds a name, phone, email, address, door code or tag; tag keeps one tag's recipients. recipients is how many recipients match; tags their tags, most used first.

Parameters

Name	In	Type	Description
`kind`	query	`string`	One of: `recipient`, `place`, `customer`.
`q`	query	`string`
`tag`	query	`string`	Recipients only.
`limit`	query	`integer`	Recipients: 100 (at most 1,000); customers: 25 (at most 100) a page. ≥ 1.
`pageToken`	query	`string`	Customers: `nextPageToken` (or `prevPageToken`).

cURL

curl "https://nways.ng/maps/v1/fleet/contacts" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

Contacts

Field	Type	Description
`contacts`	`Contact[]`	Required.
`contacts[].id`	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).
`contacts[].kind`	`string`	Required. One of: `recipient`, `place`, `customer`.
`contacts[].name`	`string`	Required.
`contacts[].phone`	`string`	Required.
`contacts[].altPhone`	`string`
`contacts[].email`	`string`
`contacts[].placeName`	`string`	Recipients: the drop-off's name; customers: their latest drop-off's.
`contacts[].address`	`string`
`contacts[].doorCode`	`string`
`contacts[].lat`	`number \| null`	Required. null for a customer with no address kept.
`contacts[].lng`	`number \| null`	Required.
`contacts[].notes`	`string`
`contacts[].itemDescription`	`string`
`contacts[].packageSize`	`string \| null`
`contacts[].tags`	`string[]`
`contacts[].regulars`	`integer`	Recipients: repeating deliveries to them that haven't ended.
`contacts[].hours`	`string`	Places
`contacts[].default`	`boolean`	Places: new deliveries in the console start from it.
`contacts[].deliveries`	`integer`	Customers
`contacts[].addresses`	`integer`	Customers
`contacts[].lastDeliveryAt`	`string (date-time)`	Customers
`contacts[].createdAt`	`string (date-time)`
`contacts[].updatedAt`	`string (date-time)`
`recipients`	`integer`
`tags`	`object[]`
`tags[].tag`	`string`
`tags[].count`	`integer`
`nextPageToken`	`string`
`prevPageToken`	`string`

200 OK

{
  "contacts": [
    {
      "id": "ben_4fQ9xLm2Za",
      "kind": "recipient",
      "name": "string",
      "phone": "string",
      "altPhone": "string",
      "email": "string",
      "placeName": "string",
      "address": "string",
      "doorCode": "string",
      "lat": 0,
      "lng": 0,
      "notes": "string",
      "itemDescription": "string",
      "packageSize": "string",
      "tags": [
        "string"
      ],
      "regulars": 0,
      "hours": "string",
      "default": true,
      "deliveries": 0,
      "addresses": 0,
      "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
      "createdAt": "2026-10-15T09:00:00+01:00",
      "updatedAt": "2026-10-15T09:00:00+01:00"
    }
  ],
  "recipients": 0,
  "tags": [
    {
      "tag": "string",
      "count": 0
    }
  ],
  "nextPageToken": "string",
  "prevPageToken": "string"
}

Errors

default Error

Save a recipient or add a pickup place

POST https://nways.ng/maps/v1/fleet/contacts

kind is recipient (a saved drop-off: name, phones, email, placeName, address, doorCode, lat, lng, notes, itemDescription, packageSize, tags; up to 5,000) or place (a pickup place: name, doorCode, address, lat, lng, phone, hours, default; up to 200; your first is the default). Customers come from deliveries and can't be made here. name, lat and lng are required.

Request body

kind (recipient or place) and that kind's fields; name, lat and lng are required to make one.

Field	Type	Description
`kind`	`string`	One of: `recipient`, `place`.
`name`	`string`	Up to 100 characters.
`phone`	`string`
`altPhone`	`string`	Recipients
`email`	`string`	Recipients
`placeName`	`string`	Recipients
`address`	`string`	Up to 300 characters.
`doorCode`	`string`	Up to 32 characters.
`lat`	`number`
`lng`	`number`
`notes`	`string`	Recipients
`itemDescription`	`string`	Recipients
`packageSize`	`string \| null`	Recipients
`tags`	`string[]`	Recipients At most 8 items.
`hours`	`string`	Places Up to 200 characters.
`default`	`boolean`	Places

cURL

curl -X POST "https://nways.ng/maps/v1/fleet/contacts" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"recipient","name":"Mama Put","phone":"+234 803 555 0101","address":"12 Herbert Macaulay Way","lat":6.5095,"lng":3.3711,"tags":["Shop"]}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "kind": "recipient",
    "name": "Mama Put",
    "phone": "+234 803 555 0101",
    "address": "12 Herbert Macaulay Way",
    "lat": 6.5095,
    "lng": 3.3711,
    "tags": [
      "Shop"
    ]
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/fleet/contacts",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"kind": "recipient", "name": "Mama Put", "phone": "+234 803 555 0101", "address": "12 Herbert Macaulay Way", "lat": 6.5095, "lng": 3.3711, "tags": ["Shop"]},
    timeout=10,
)
data = res.json()

Response

Saved

Field	Type	Description
`id`	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).
`kind`	`string`	Required. One of: `recipient`, `place`, `customer`.
`name`	`string`	Required.
`phone`	`string`	Required.
`altPhone`	`string`
`email`	`string`
`placeName`	`string`	Recipients: the drop-off's name; customers: their latest drop-off's.
`address`	`string`
`doorCode`	`string`
`lat`	`number \| null`	Required. null for a customer with no address kept.
`lng`	`number \| null`	Required.
`notes`	`string`
`itemDescription`	`string`
`packageSize`	`string \| null`
`tags`	`string[]`
`regulars`	`integer`	Recipients: repeating deliveries to them that haven't ended.
`hours`	`string`	Places
`default`	`boolean`	Places: new deliveries in the console start from it.
`deliveries`	`integer`	Customers
`addresses`	`integer`	Customers
`lastDeliveryAt`	`string (date-time)`	Customers
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

201 OK

{
  "id": "ben_4fQ9xLm2Za",
  "kind": "recipient",
  "name": "string",
  "phone": "string",
  "altPhone": "string",
  "email": "string",
  "placeName": "string",
  "address": "string",
  "doorCode": "string",
  "lat": 0,
  "lng": 0,
  "notes": "string",
  "itemDescription": "string",
  "packageSize": "string",
  "tags": [
    "string"
  ],
  "regulars": 0,
  "hours": "string",
  "default": true,
  "deliveries": 0,
  "addresses": 0,
  "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Errors

default Error

Your own addresses first while a stop is typed

GET https://nways.ng/maps/v1/fleet/contacts/addresses

Your pickup places and the drop-offs you used before, matching q (every word, in the name, address or door code), the most recently used first; at most limit (5, up to 10).

Parameters

Name	In	Type	Description
`q`	query	`string`
`limit`	query	`integer`	Default: `5`. ≥ 1, ≤ 10.

cURL

curl "https://nways.ng/maps/v1/fleet/contacts/addresses" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/addresses', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts/addresses",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

Addresses

Field	Type	Description
`addresses`	`object[]`	Required.

200 OK

{
  "addresses": [
    {}
  ]
}

Errors

default Error

Get a contact

GET https://nways.ng/maps/v1/fleet/contacts/{contactId}

Parameters

Name	In	Type	Description
`contactId`	path	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).

cURL

curl "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

Contact

Field	Type	Description
`id`	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).
`kind`	`string`	Required. One of: `recipient`, `place`, `customer`.
`name`	`string`	Required.
`phone`	`string`	Required.
`altPhone`	`string`
`email`	`string`
`placeName`	`string`	Recipients: the drop-off's name; customers: their latest drop-off's.
`address`	`string`
`doorCode`	`string`
`lat`	`number \| null`	Required. null for a customer with no address kept.
`lng`	`number \| null`	Required.
`notes`	`string`
`itemDescription`	`string`
`packageSize`	`string \| null`
`tags`	`string[]`
`regulars`	`integer`	Recipients: repeating deliveries to them that haven't ended.
`hours`	`string`	Places
`default`	`boolean`	Places: new deliveries in the console start from it.
`deliveries`	`integer`	Customers
`addresses`	`integer`	Customers
`lastDeliveryAt`	`string (date-time)`	Customers
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

200 OK

{
  "id": "ben_4fQ9xLm2Za",
  "kind": "recipient",
  "name": "string",
  "phone": "string",
  "altPhone": "string",
  "email": "string",
  "placeName": "string",
  "address": "string",
  "doorCode": "string",
  "lat": 0,
  "lng": 0,
  "notes": "string",
  "itemDescription": "string",
  "packageSize": "string",
  "tags": [
    "string"
  ],
  "regulars": 0,
  "hours": "string",
  "default": true,
  "deliveries": 0,
  "addresses": 0,
  "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Errors

default Error

Edit a recipient or a pickup place

PATCH https://nways.ng/maps/v1/fleet/contacts/{contactId}

The kind's fields as when made (kind may be left out; it can't change). A customer is the record of their deliveries and can't be edited (400): save them as a recipient.

Parameters

Name	In	Type	Description
`contactId`	path	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).

Request body

kind (recipient or place) and that kind's fields; name, lat and lng are required to make one.

Field	Type	Description
`kind`	`string`	One of: `recipient`, `place`.
`name`	`string`	Up to 100 characters.
`phone`	`string`
`altPhone`	`string`	Recipients
`email`	`string`	Recipients
`placeName`	`string`	Recipients
`address`	`string`	Up to 300 characters.
`doorCode`	`string`	Up to 32 characters.
`lat`	`number`
`lng`	`number`
`notes`	`string`	Recipients
`itemDescription`	`string`	Recipients
`packageSize`	`string \| null`	Recipients
`tags`	`string[]`	Recipients At most 8 items.
`hours`	`string`	Places Up to 200 characters.
`default`	`boolean`	Places

cURL

curl -X PATCH "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za" \
  -H "X-NWays-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"recipient","name":"string","phone":"string","altPhone":"string","email":"string","placeName":"string","address":"string","doorCode":"string","lat":0,"lng":0,"notes":"string","itemDescription":"string","packageSize":"string","tags":["string"],"hours":"string","default":true}'

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za', {
  method: 'PATCH',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "kind": "recipient",
    "name": "string",
    "phone": "string",
    "altPhone": "string",
    "email": "string",
    "placeName": "string",
    "address": "string",
    "doorCode": "string",
    "lat": 0,
    "lng": 0,
    "notes": "string",
    "itemDescription": "string",
    "packageSize": "string",
    "tags": [
      "string"
    ],
    "hours": "string",
    "default": true
  }),
})
const data = await res.json()

Python

import os
import requests

res = requests.patch(
    "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"kind": "recipient", "name": "string", "phone": "string", "altPhone": "string", "email": "string", "placeName": "string", "address": "string", "doorCode": "string", "lat": 0, "lng": 0, "notes": "string", "itemDescription": "string", "packageSize": "string", "tags": ["string"], "hours": "string", "default": True},
    timeout=10,
)
data = res.json()

Response

Contact

Field	Type	Description
`id`	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).
`kind`	`string`	Required. One of: `recipient`, `place`, `customer`.
`name`	`string`	Required.
`phone`	`string`	Required.
`altPhone`	`string`
`email`	`string`
`placeName`	`string`	Recipients: the drop-off's name; customers: their latest drop-off's.
`address`	`string`
`doorCode`	`string`
`lat`	`number \| null`	Required. null for a customer with no address kept.
`lng`	`number \| null`	Required.
`notes`	`string`
`itemDescription`	`string`
`packageSize`	`string \| null`
`tags`	`string[]`
`regulars`	`integer`	Recipients: repeating deliveries to them that haven't ended.
`hours`	`string`	Places
`default`	`boolean`	Places: new deliveries in the console start from it.
`deliveries`	`integer`	Customers
`addresses`	`integer`	Customers
`lastDeliveryAt`	`string (date-time)`	Customers
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

200 OK

{
  "id": "ben_4fQ9xLm2Za",
  "kind": "recipient",
  "name": "string",
  "phone": "string",
  "altPhone": "string",
  "email": "string",
  "placeName": "string",
  "address": "string",
  "doorCode": "string",
  "lat": 0,
  "lng": 0,
  "notes": "string",
  "itemDescription": "string",
  "packageSize": "string",
  "tags": [
    "string"
  ],
  "regulars": 0,
  "hours": "string",
  "default": true,
  "deliveries": 0,
  "addresses": 0,
  "lastDeliveryAt": "2026-10-15T09:00:00+01:00",
  "createdAt": "2026-10-15T09:00:00+01:00",
  "updatedAt": "2026-10-15T09:00:00+01:00"
}

Errors

default Error

Delete a contact (a customer is forgotten with their addresses)

DELETE https://nways.ng/maps/v1/fleet/contacts/{contactId}

Deliveries already made keep what they were given; a forgotten customer's deliveries stay with your fleet's retention.

Parameters

Name	In	Type	Description
`contactId`	path	`string`	Required. ben_… (recipient), plc_… (place) or cus_… (customer).

cURL

curl -X DELETE "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za', {
  method: 'DELETE',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.delete(
    "https://nways.ng/maps/v1/fleet/contacts/ben_4fQ9xLm2Za",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

Deleted

No content.

Errors

default Error

A contact's addresses

GET https://nways.ng/maps/v1/fleet/contacts/{contactId}/addresses

A customer's drop-offs, last used first, a page at a time (q, limit, pageToken); a recipient's or place's one address.

Parameters

Name	In	Type	Description
`contactId`	path	`string`	Required.
`q`	query	`string`
`limit`	query	`integer`	Default: `25`. ≥ 1, ≤ 100.
`pageToken`	query	`string`

cURL

curl "https://nways.ng/maps/v1/fleet/contacts/string/addresses" \
  -H "X-NWays-Api-Key: YOUR_API_KEY"

JavaScript

const res = await fetch('https://nways.ng/maps/v1/fleet/contacts/string/addresses', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()

Python

import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/fleet/contacts/string/addresses",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Response

Addresses

Field	Type	Description
`addresses`	`Address[]`	Required.
`addresses[].id`	`string`	Required.
`addresses[].name`	`string`	Required.
`addresses[].address`	`string`	Required.
`addresses[].doorCode`	`string`	Required. The NIPOST or GhanaPost code the address starts with ("" for none).
`addresses[].lat`	`number`	Required.
`addresses[].lng`	`number`	Required.
`addresses[].uses`	`integer`	Required. Deliveries that went there.
`addresses[].lastUsedAt`	`string (date-time)`	Required.
`total`	`integer`	Required.
`nextPageToken`	`string`
`prevPageToken`	`string`

200 OK

{
  "addresses": [
    {
      "id": "adr_8KwP2nVd5T",
      "name": "string",
      "address": "string",
      "doorCode": "string",
      "lat": 0,
      "lng": 0,
      "uses": 0,
      "lastUsedAt": "2026-10-15T09:00:00+01:00"
    }
  ],
  "total": 0,
  "nextPageToken": "string",
  "prevPageToken": "string"
}

Errors

default Error