ChatmaidChatmaid DevelopersChatmaid Dev
Docs
DashboardStart Building
Management API

Phone Numbers

List connected phone numbers and inspect connection status.

Overview

Phone number data is available through standard API-key endpoints. Environment is inferred from your API key prefix on a single host.

  • GET /v1/phone-numbers
  • GET /v1/phone-numbers/:id
  • GET /v1/phone-numbers/:id/status

The :id path parameter accepts either the internal phone ID or an E.164 phone number. When using a phone number in path, URL-encode it (for example %2B15551234567).

Integration host: https://developers-api.chatmaid.net.

List Numbers

GET/v1/phone-numbersAuth: API key

List all phone numbers in the account that owns the API key.

Response

  • data[].id
  • data[].phoneNumber
  • data[].displayName
  • data[].connectionStatus (connected | disconnected | connecting)

List Auth and Status Codes

ItemValue
Recommended scopephone_numbers:read
Backward-compatible scopephone-numbers:read
Success code200
Error codes401, 403, 429
List Phone Numbers
curl -X GET https://developers-api.chatmaid.net/v1/phone-numbers \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "phoneNumber": "+15551234567",
      "displayName": "Primary Sender",
      "connectionStatus": "connected",
      "lastConnectedAt": "2026-02-06T14:10:00.000Z",
      "lastDisconnectedAt": null,
      "createdAt": "2026-02-01T10:20:00.000Z",
      "updatedAt": "2026-02-06T14:10:00.000Z"
    }
  ]
}

Get One Number

GET/v1/phone-numbers/:idAuth: API key

Get a single phone number using either internal ID or URL-encoded E.164 number.

Read One Request Contract

ParameterInTypeRequiredRules
idPathstringYesAccepts phone ID or URL-encoded E.164 (example: %2B15551234567).
Required scope-phone_numbers:readYesAlso accepts phone-numbers:read.
Status codes-200 | 401 | 403 | 404 | 429YesTypical read endpoint responses.
Get Phone Number
curl -X GET "https://developers-api.chatmaid.net/v1/phone-numbers/%2B15551234567" \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "phoneNumber": "+15551234567",
    "displayName": "Primary Sender",
    "connectionStatus": "connected",
    "lastConnectedAt": "2026-02-06T14:10:00.000Z",
    "lastDisconnectedAt": null,
    "createdAt": "2026-02-01T10:20:00.000Z",
    "updatedAt": "2026-02-06T14:10:00.000Z"
  }
}

Connection Status

GET/v1/phone-numbers/:id/statusAuth: API key

Get up-to-date WhatsApp connection state by internal ID or URL-encoded E.164 number.

Status Request Contract

ParameterInTypeRequiredRules
idPathstringYesAccepts phone ID or URL-encoded E.164 (example: %2B15551234567).
Required scope-phone_numbers:readYesAlso accepts phone-numbers:read.
Status codes-200 | 401 | 403 | 404 | 429YesTypical status endpoint responses.
Get Phone Status
curl -X GET "https://developers-api.chatmaid.net/v1/phone-numbers/%2B15551234567/status" \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "phoneNumber": "+15551234567",
    "connectionStatus": "connected",
    "lastConnectedAt": "2026-02-06T14:10:00.000Z",
    "lastDisconnectedAt": null,
    "updatedAt": "2026-02-06T14:10:00.000Z"
  }
}
Write Operations
Phone registration and connect/disconnect lifecycle remain dashboard-managed. Standard API endpoints are read-focused for integration runtime discovery.
On This Page