Managing contacts

A contact is the person on the other side of a conversation. The send endpoint creates one for you when you address a phone number it has never seen, so most integrations only read contacts. Create and update them directly when your own system is the source of truth for who your customers are.

All endpoints on this page take the same api_access_token header as the send endpoint.

Find a contact

POST /accounts/{account_id}/developer/contacts/filter

Each item in payload is one condition on a contact attribute. query_operator joins it to the next one and is omitted on the last item.

$
curl -X POST https://your-installation.example.com/api/v1/accounts/1/developer/contacts/filter \
>
  -H "api_access_token: $HAMS_TOKEN" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "payload": [
>
      { "attribute_key": "phone_number", "filter_operator": "equal_to", "values": ["+971500000000"] }
>
    ]
>
  }'

1
{
2
  "payload": [
3
    {
4
      "id": 42,
5
      "name": "Katherine Johnson",
6
      "email": "katherine@example.com",
7
      "phone_number": "+971500000000",
8
      "identifier": "cust_9931",
9
      "custom_attributes": { "plan": "pro" }
10
    }
11
  ],
12
  "meta": { "count": 1, "current_page": 1 }
13
}

Create a contact

POST /accounts/{account_id}/developer/contacts

1
{
2
  "name": "Katherine Johnson",
3
  "email": "katherine@example.com",
4
  "phone_number": "+971500000000",
5
  "identifier": "cust_9931",
6
  "custom_attributes": { "plan": "pro" }
7
}

email, phone_number and identifier are each unique within the account. Reusing a value that another contact already holds fails with 422. Set identifier to your own primary key so you can filter the same person back out later without matching on a number they may change.

Update a contact

PATCH /accounts/{account_id}/developer/contacts/{id}

Only the fields you send are changed, with one exception: custom_attributes replaces the stored object rather than merging into it. Send the full set every time.

1
{ "custom_attributes": { "plan": "enterprise", "renewal": "2027-01-31" } }

Listing

GET /accounts/{account_id}/developer/contacts?page=1

Pages hold 15 contacts. The response omits contacts with no email, phone number or identifier, so the count here is smaller than the total in the dashboard.