List & search contacts

GET

/api/v2/contacts

curl --request GET \
  --url 'https://api.sipstack.com/api/v2/contacts?page=1&limit=50' \
  --header 'x-api-key: <x-api-key>'

• Production

Lists your organization’s contacts, newest first. Hides soft-deleted and merged rows. Requires the contacts:read scope. Supports offset or keyset (cursor / next_cursor) paging.

Incremental sync: pass updated_since to get only contacts changed strictly after that timestamp, ordered oldest change first (by updated_at, then id). Page with next_cursor — the cursor keeps the full-precision timestamp, so pages never repeat or skip a contact. Store the updated_at of the last contact you processed and pass it as updated_since on your next sync. Without updated_since the listing is unchanged (newest first).

Authorizations

• apiKeyAuth

Parameters

Query Parameters

page

integer

default: 1 >= 1

limit

integer

default: 50 >= 1 <= 200

cursor

string

Opaque keyset cursor from a previous response’s next_cursor.

search

string

Case-insensitive match across first/last name, phone, email, and business.

phone

string

Search by phone number — digits matched against the stored number (≥3 digits).

tag

string

Return only contacts carrying this exact tag.

updated_since

string format: date-time

ISO-8601 timestamp. Return only contacts changed strictly after it, oldest change first (updated_at ascending, then id). Page with next_cursor. Example: 2026-10-01T00:00:00Z. An unparseable date returns 400.

Responses

200

Paginated contact list.

Media type application/json

object

success

boolean

data

Array<object>

A contact record. POST /api/v2/contacts returns the compact subset (id, uuid, phone_number, names, email, tags, consent_status, consent_date, implied_consent_basis, implied_consent_basis_date, consent_evidence, created_at); the list/get/update endpoints return the full record below.

object

id

string format: uuid

uuid

string format: uuid

phone_number

string

first_name

string

nullable

last_name

string

nullable

email

string

nullable

business

string

nullable

tags

Array<string>

custom_fields

object

key

additional properties

any

consent_status

string

Allowed values: implied express none

consent_date

string format: date-time

nullable

implied_consent_basis

The declared CASL basis for implied consent; null = undeclared. See impliedConsentBasis on create.

string

nullable

Allowed values: ebr_purchase ebr_contract ebr_inquiry nbr conspicuous_publication disclosed_address

implied_consent_basis_date

The date the basis runs from (for ebr_contract, the contract end date).

string format: date-time

nullable

consent_evidence

Evidence recorded for the consent.

string

nullable

is_opted_out

boolean

is_blocked

boolean

is_archived

boolean

is_starred

boolean

last_contacted_at

string format: date-time

nullable

total_messages_sent

integer

total_messages_received

integer

source

How the contact was created (e.g. api).

string

nullable

created_at

string format: date-time

updated_at

string format: date-time

pagination

Page metadata returned by the paginated Developer API list endpoints. Per-endpoint limit defaults and caps vary (see each endpoint’s limit parameter). In keyset (cursor) mode page, total, and totalPages are null — walk pages via next_cursor instead.

object

page

integer

nullable

limit

Items per page (the default and maximum vary by endpoint).

integer

total

Total matching records across all pages (null in cursor mode).

integer

nullable

totalPages

integer

nullable

next_cursor

string

nullable

Example

{
  "data": [
    {
      "phone_number": "+14165550100",
      "consent_status": "implied",
      "implied_consent_basis": "ebr_purchase"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 143,
    "totalPages": 6
  }
}

400

Invalid cursor, phone filter, or updated_since date.

Media type application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

401

Missing or invalid API key.

Media type application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

403

The key is missing the contacts:read scope.

Media type application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}

500

Internal error.

Media type application/json

Inline error shape used by the messaging API and management endpoints.

object

success

boolean

error

string

Example

{
  "success": false,
  "error": "Recipient phone number (to) is required"
}