Contacts

Contacts API

Manage your customer phonebook programmatically — create, read, update and delete contacts; group them; and target campaigns by group. The Contacts API is the source of truth for who can be messaged across SMS, WhatsApp and Premium SMS.

All endpoints live under https://sozuri.net/api/v1/contacts. For compatibility with the Contacts schema, this API uses snake_case field names.

Common headers

Content-Type: application/json
Authorization: Bearer Your_Project_API_KEY

List contacts

Returns all contacts in the project. Pass an optional group to filter to a single group; results are paginated 1,000 per page.

GET/api/v1/contacts
Request body
{
    "project": "Shopify",
    "group": "Shopify Mpesa"
}
Request parameters
FieldRequiredTypeDescription
projectYesStringThe Sozuri project that owns the API key.
groupNoStringLimit results to contacts in this group. Omit to return all contacts.
Sample response
{
    "group": "Shopify Mpesa",
    "contacts": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "fname": null,
                "mname": null,
                "lname": null,
                "mobile": "254725164293",
                "email": null,
                "city": null,
                "company": null,
                "created_at": "2024-03-21T07:06:37.000000Z"
            },
            {
                "id": 2,
                "fname": null,
                "mname": null,
                "lname": null,
                "mobile": "254723364291",
                "email": null,
                "city": null,
                "company": null,
                "created_at": "2024-03-21T07:13:21.000000Z"
            }
        ],
        "first_page_url": "https://sozuri.net/api/v1/contacts?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "https://sozuri.net/api/v1/contacts?page=1",
        "next_page_url": null,
        "path": "https://sozuri.net/api/v1/contacts",
        "per_page": 1000,
        "prev_page_url": null,
        "to": 3,
        "total": 3
    }
}
Response fields
FieldTypeDescription
groupStringEchoes back the requested group (empty if none).
contacts.data[]ArrayThe contacts in this page. Each contact has: id, fname, mname, lname, mobile, email, city, company, created_at.
contacts.current_pageNumberThe page returned.
contacts.per_pageNumberPage size (1,000).
contacts.totalNumberTotal contacts matching the filter.
contacts.next_page_urlStringURL for the next page, or null on the last page.

Get one contact

Fetch a single contact by its numeric id (or mobile number, when ID is unknown).

GET/api/v1/contacts/{id}
Request body
{
    "project": "Shopify"
}
Sample response
{
    "contact": {
        "id": 456,
        "fname": "Suzan",
        "mname": "Joy",
        "lname": null,
        "mobile": "254777222555",
        "email": "lawren66@gmail.com",
        "city": "Nairobi",
        "company": "Sozu PLC",
        "created_at": "2024-03-26T16:32:44.000000Z"
    }
}

Create contacts (bulk)

Add one or many contacts in a single call. New contacts can be assigned to a group on creation.

POST/api/v1/contacts
Request body
{
    "project": "Kalro",
    "group": "shop-contacts",
    "contacts": [
        {
            "fname": "Lawrence",
            "mname": "Joel",
            "lname": "",
            "mobile": "254725164290",
            "city": "Nairobi",
            "company": "Sozu PLC",
            "email": "lawl@example.com"
        },
        {
            "fname": "Lucy",
            "mname": "",
            "lname": "Susan",
            "mobile": "254725164291",
            "city": "Kitui",
            "company": "Ivy Ltd.",
            "email": "ivy@example.com"
        }
    ]
}
Sample response
{
    "message": "Contacts created successfully"
}

Update a contact

Update fields on an existing contact and (optionally) move them between groups.

PUT/api/v1/contacts/{id}
Request body
{
    "project": "Shopify",
    "group": "mpesa-contacts",
    "contact": {
        "fname": "Suzan",
        "mname": "Joy",
        "lname": "",
        "mobile": "254777222555",
        "city": "Nairobi",
        "company": "Sozu PLC",
        "email": "lawren66@gmail.com"
    }
}
Sample response
{
    "message": "Contact updated successfully"
}

Delete a contact

Remove a contact from your project. They will no longer receive messages targeted at any of their groups.

DELETE/api/v1/contacts/{id}
Request body
{
    "project": "Shopify"
}
Sample response
{
    "message": "Contact deleted successfully"
}

Use cases

How teams build their messaging audience on top of the Contacts API.

Sync from your CRM

Push new signups from HubSpot, Pipedrive or your own DB into Sozuri groups in real time — campaigns always target the freshest list.

E-commerce abandoned cart

Create a contact when a Shopify customer abandons checkout, drop them in the abandoned-cart group, and trigger a recovery SMS an hour later.

Segmented broadcasts

Build groups like nairobi-vip, mama-mboga, silver-tier and send tailored offers to each — lifts open rates without bloating your stack.

Opt-out compliance

When a customer texts STOP, your STOP webhook calls DELETE here. Compliance handled in one place.

Build a smarter messaging audience.

Pipe your customer data into Sozuri groups today and start sending more relevant SMS and WhatsApp.

Get an API key See SMS endpoint