// contacts & lists

Contacts & lists

Save phone numbers as named contacts, group them into lists, and send to an entire list with a single API call. Contacts are upserted on phone number so imports are always safe to re-run.

Contacts

A contact is a phone number with optional metadata. Every write operation upserts on the phone number, so you can safely call POST /contacts for every signup without worrying about duplicates.

curl -X POST https://sms-api.ekrasunya.com/v1/contacts \
  -H "X-API-Key: eksms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "9818000000",
    "name": "Ram Shrestha",
    "email": "[email protected]",
    "notes": "Key account - Kathmandu branch"
  }'

Request parameters

Field	Type	Description
phone	string	Required. 10-digit Nepali mobile number (e.g. `9818000000`). `+977` / `977` prefixes are normalized away. Must be unique per workspace; a matching number is updated in place.
name	string	Optional. Display name for the contact.
email	string	Optional. Email address stored for reference only.
notes	string	Optional. Free-text notes for internal use.

Other contact endpoints

Endpoint	Description
`GET /contacts`	List contacts. Supports `limit`, `offset`, `search` (matches name or phone), and `listId` (filter to members of a specific list). Returns a paginated envelope with a `meta` object.
`GET /contacts/:id`	Retrieve a single contact by its UUID.
`PATCH /contacts/:id`	Update any subset of `phone`, `name`, `email`, `notes`. Only fields present in the body are changed.
`DELETE /contacts/:id`	Permanently remove a contact. The contact is also removed from any lists it belongs to.
`POST /contacts/bulk`	Import up to 1000 contacts in one request. Returns `{ created, updated, skipped }`. Each item follows the same schema as `POST /contacts`; phone is the only required field per row.

curl "https://sms-api.ekrasunya.com/v1/contacts?limit=20&offset=0&search=ram" \
  -H "X-API-Key: eksms_..."

Lists

A list is a named group of contacts. You can seed members at creation time by passing contactIds (existing contact UUIDs) or inline contacts (phone numbers that are upserted automatically).

curl -X POST https://sms-api.ekrasunya.com/v1/lists \
  -H "X-API-Key: eksms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kathmandu staff",
    "description": "All Kathmandu branch employees",
    "contacts": [
      { "phone": "9818000000" },
      { "phone": "9808000001" }
    ]
  }'

Request parameters

Field	Type	Description
name	string	Required. Display name for the list.
description	string	Optional. Free-text description for internal use.
contactIds	string[]	Optional. UUIDs of existing contacts to add as initial members.
contacts	object[]	Optional. Inline contacts (same shape as `POST /contacts`) to upsert and add as initial members. You can mix `contactIds` and `contacts` in the same request.

Members and other list endpoints

Endpoint	Description
`GET /lists`	Paginated list of all lists. Each object includes `memberCount`. Supports `limit` and `offset`.
`GET /lists/:id`	Retrieve a list including a paginated `members` array.
`PATCH /lists/:id`	Update `name` and/or `description`.
`DELETE /lists/:id`	Permanently delete the list. Member contacts are not deleted.
`POST /lists/:id/members`	Add members. Body accepts `contactIds` (UUIDs) and/or `contacts` (inline phone objects to upsert first).
`DELETE /lists/:id/members`	Remove members. Body accepts `contactIds` (UUIDs). Contacts themselves are not deleted.

curl -X POST https://sms-api.ekrasunya.com/v1/lists/<list-id>/members \
  -H "X-API-Key: eksms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [{ "phone": "9841000002" }],
    "contactIds": ["<existing-contact-uuid>"]
  }'

Send to a list

To send an SMS to every member of a list, pass listIds to POST /v1/messages. Members are expanded and deduped at send time, so overlapping lists are safe. You can combine listIds with explicit recipients in the same request.

curl -X POST https://sms-api.ekrasunya.com/v1/messages \
  -H "X-API-Key: eksms_..." \
  -H "Content-Type: application/json" \
  -d '{
    "listIds": ["<list-id>"],
    "text": "Sale starts today!"
  }'

Required scopes

Use contacts:read to list or retrieve contacts and lists. Use contacts:write to create, update, delete, or bulk-import contacts, and to create, modify, or delete lists and their members. Sending to a list also requires the messages:send scope on the same key.

Next: Send a message · Errors