Contacts API
Create, read, update and delete the people you message, or upsert up to 500 in one request. Put contacts in lists when you want to send a campaign to a group.
/contacts/List contacts
List the project's contacts. Search by phone, name or email, or filter by whether they opted in.
Query Parameters
searchstringSearch by phone, name or email.
opted_inbooleanFilter by opt-in status (true or false).
pageintegerPage number to return. Defaults to 1.
page_sizeintegerNumber of contacts per page. Defaults to 30, maximum 1000.
{
"count": 1,
"next": null,
"previous": null,
"results": [
{
"id": "25659b22-d307-4912-907e-63ed0b353f39",
"phone": "+233201234567",
"first_name": "Alice",
"last_name": "Mensah",
"email": "[email protected]",
"attributes": {},
"opted_in": true,
"opt_in_source": "MANUAL",
"opted_out_at": null,
"created_at": "2026-04-01T19:05:07.109303Z"
}
]
}/contacts/Create a contact
Create a contact. It needs a phone number, an email address, or both. Pass list_ids to add it to lists at the same time.
Body Parameters
phonestringPhone number in E.164 format, such as +233241234567. Maximum 30 characters. Required if email is omitted.
emailstringA valid email address. Required if phone is omitted.
first_namestringContact's first name. Maximum 100 characters.
last_namestringContact's last name. Maximum 100 characters.
attributesobjectCustom key-value attributes for the contact.
opted_inbooleanWhether the contact has opted in to receive messages.
opt_in_sourcestringHow the contact opted in. One of API, CSV, or MANUAL.
list_idsstring[]Array of list IDs to add the contact to. Maximum 10.
{
"phone": "+233241234567",
"email": "[email protected]",
"first_name": "Alice",
"last_name": "Mensah",
"attributes": {},
"opted_in": true,
"opt_in_source": "API",
"list_ids": ["a7bd4b07-7e58-4785-933c-424d728a2790"]
}{
"id": "1597951f-e00f-42c3-9924-26a0044ba820",
"phone": "+233241234567",
"first_name": "Alice",
"last_name": "Mensah",
"email": "[email protected]",
"attributes": {},
"opted_in": true,
"opt_in_source": "API",
"opted_out_at": null,
"created_at": "2026-04-03T13:56:18.900086Z"
}/contacts/{contact_id}/Get a contact
Get one contact by ID, along with the lists it belongs to.
Path Parameters
contact_idstringrequiredThe UUID of the contact.
{
"id": "25659b22-d307-4912-907e-63ed0b353f39",
"phone": "+233201234567",
"first_name": "Alice",
"last_name": "Mensah",
"email": "[email protected]",
"attributes": {},
"opted_in": true,
"opt_in_source": "MANUAL",
"opted_out_at": null,
"created_at": "2026-04-01T19:05:07.109303Z",
"lists": [
{
"id": "a7bd4b07-7e58-4785-933c-424d728a2790",
"name": "VIP Customers",
"created_at": "2026-04-03T13:55:44.050666Z"
}
]
}/contacts/{contact_id}/Update a contact
Change some of a contact's fields. Anything you leave out stays as it is. You can change first_name, last_name, email, attributes and opted_in. A contact must keep a phone number or an email address.
Path Parameters
contact_idstringrequiredThe UUID of the contact.
Body Parameters
first_namestringContact's first name. Maximum 100 characters.
last_namestringContact's last name. Maximum 100 characters.
emailstringA valid email address. It can only be cleared if the contact has a phone number.
attributesobjectCustom key-value attributes for the contact.
opted_inbooleanWhether the contact has opted in to receive messages.
{
"last_name": "Owusu",
"opted_in": true
}{
"id": "25659b22-d307-4912-907e-63ed0b353f39",
"phone": "+233201234567",
"first_name": "Alice",
"last_name": "Owusu",
"email": "[email protected]",
"attributes": {},
"opted_in": true,
"opt_in_source": "MANUAL",
"opted_out_at": null,
"created_at": "2026-04-01T19:05:07.109303Z"
}/contacts/{contact_id}/Delete a contact
Soft-delete a contact. Returns 204 No Content.
Path Parameters
contact_idstringrequiredThe UUID of the contact.
No response body.
/contacts/bulk/Bulk upsert
Create or update up to 500 contacts in one request. Each contact needs a phone or an email. Sailup matches existing contacts by phone, or by email when there is no phone.
Body Parameters
contactsobject[]requiredArray of contact objects, each using the same fields as Create a contact. Maximum 500 items.
{
"contacts": [
{
"phone": "+233241000002",
"first_name": "Bob"
},
{
"email": "[email protected]",
"first_name": "Ama"
}
]
}{
"imported": 2,
"skipped": 0,
"failed": 0,
"errors": []
}