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.

GET/contacts/

List contacts

List the project's contacts. Search by phone, name or email, or filter by whether they opted in.

Query Parameters

searchstring

Search by phone, name or email.

opted_inboolean

Filter by opt-in status (true or false).

pageinteger

Page number to return. Defaults to 1.

page_sizeinteger

Number of contacts per page. Defaults to 30, maximum 1000.

200 OKResponse
{
  "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"
    }
  ]
}
POST/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

phonestring

Phone number in E.164 format, such as +233241234567. Maximum 30 characters. Required if email is omitted.

emailstring

A valid email address. Required if phone is omitted.

first_namestring

Contact's first name. Maximum 100 characters.

last_namestring

Contact's last name. Maximum 100 characters.

attributesobject

Custom key-value attributes for the contact.

opted_inboolean

Whether the contact has opted in to receive messages.

opt_in_sourcestring

How the contact opted in. One of API, CSV, or MANUAL.

list_idsstring[]

Array of list IDs to add the contact to. Maximum 10.

Request Body
{
  "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"]
}
201 CreatedCreated
{
  "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"
}
GET/contacts/{contact_id}/

Get a contact

Get one contact by ID, along with the lists it belongs to.

Path Parameters

contact_idstringrequired

The UUID of the contact.

200 OKResponse
{
  "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"
    }
  ]
}
PATCH/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_idstringrequired

The UUID of the contact.

Body Parameters

first_namestring

Contact's first name. Maximum 100 characters.

last_namestring

Contact's last name. Maximum 100 characters.

emailstring

A valid email address. It can only be cleared if the contact has a phone number.

attributesobject

Custom key-value attributes for the contact.

opted_inboolean

Whether the contact has opted in to receive messages.

Request Body
{
  "last_name": "Owusu",
  "opted_in": true
}
200 OKResponse
{
  "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"
}
DELETE/contacts/{contact_id}/

Delete a contact

Soft-delete a contact. Returns 204 No Content.

Path Parameters

contact_idstringrequired

The UUID of the contact.

204 No ContentNo content

No response body.

POST/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[]required

Array of contact objects, each using the same fields as Create a contact. Maximum 500 items.

Request Body
{
  "contacts": [
    {
      "phone": "+233241000002",
      "first_name": "Bob"
    },
    {
      "email": "[email protected]",
      "first_name": "Ama"
    }
  ]
}
200 OKResponse
{
  "imported": 2,
  "skipped": 0,
  "failed": 0,
  "errors": []
}