Get contacts list

Retrieves a paginated list of contacts for the authenticated customer. Supports filtering by search term, channel, or phone number.

GET
/v3/contacts

Query Parameters

page*integer

Page number (1-indexed)

Formatint32
page_size*integer

Number of items per page

Formatint32
search?|

Optional search term for filtering contacts

channel?|

Optional channel filter (sms, whatsapp)

phone?|

Optional phone number filter (alternative to list view)

Header Parameters

x-profile-id?string

Profile UUID to scope the request to a child profile. Only organization API keys can use this header. The profile must belong to the calling organization.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://api.sent.dm/v3/contacts?page=1&page_size=20"
{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "phone_number": "+1234567890",
        "format_e164": "+1234567890",
        "format_international": "+1 234-567-890",
        "format_national": "(234) 567-890",
        "format_rfc": "tel:+1-234-567-890",
        "country_code": "1",
        "region_code": "US",
        "available_channels": "sms,whatsapp",
        "default_channel": "sms",
        "opt_out": false,
        "is_inherited": false,
        "created_at": "2026-03-11T21:50:50.1887701+00:00",
        "updated_at": null
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_count": 150,
      "total_pages": 8,
      "has_more": true,
      "cursors": null
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1888357+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_005",
    "message": "Page must be greater than 0",
    "details": null,
    "doc_url": "https://docs.sent.dm/errors/VALIDATION_005"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1888376+00:00",
    "version": "v3"
  }
}
Empty
Empty
{
  "success": false,
  "data": null,
  "error": {
    "code": "RESOURCE_001",
    "message": "Contact not found with the specified phone number",
    "details": null,
    "doc_url": "https://docs.sent.dm/errors/RESOURCE_001"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1888379+00:00",
    "version": "v3"
  }
}
{
  "success": false,
  "data": null,
  "error": {
    "code": "INTERNAL_001",
    "message": "An unexpected error occurred. Please contact support with request ID: req_7X9zKp2jDw",
    "details": null,
    "doc_url": "https://docs.sent.dm/errors/INTERNAL_001"
  },
  "meta": {
    "request_id": "req_7X9zKp2jDw",
    "timestamp": "2026-03-11T21:50:50.1888382+00:00",
    "version": "v3"
  }
}

Get message activities GET

Retrieves the activity log for a specific message. Activities track the message lifecycle including acceptance, processing, sending, delivery, and any errors.

Get contact by ID GET

Retrieves a specific contact by their unique identifier. Returns detailed contact information including phone formats, available channels, and opt-out status.