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-numbers

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

List Auth and Status Codes

Item	Value
Recommended scope	`phone_numbers:read`
Backward-compatible scope	`phone-numbers:read`
Success code	`200`
Error codes	`401, 403, 429`

curl -X GET https://developers-api.chatmaid.net/v1/phone-numbers \
  -H "Authorization: Bearer sk_test_xxx"

const response = await fetch("https://developers-api.chatmaid.net/v1/phone-numbers", {
  headers: { Authorization: "Bearer " + process.env.CHATMAID_API_KEY },
});

const payload = await response.json();

import requests
import os

response = requests.get(
    "https://developers-api.chatmaid.net/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['CHATMAID_API_KEY']}"},
)

payload = response.json()

{
  "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/:id

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

Read One Request Contract

Parameter	In	Type	Required	Rules
`id`	Path	`string`	Yes	Accepts phone ID or URL-encoded E.164 (example: %2B15551234567).
Required scope	-	`phone_numbers:read`	Yes	Also accepts phone-numbers:read.
Status codes	-	`200 \| 401 \| 403 \| 404 \| 429`	Yes	Typical read endpoint responses.

curl -X GET "https://developers-api.chatmaid.net/v1/phone-numbers/%2B15551234567" \
  -H "Authorization: Bearer sk_test_xxx"

const phoneRef = encodeURIComponent("+15551234567");
const response = await fetch(`https://developers-api.chatmaid.net/v1/phone-numbers/${phoneRef}`, {
  headers: { Authorization: "Bearer " + process.env.CHATMAID_API_KEY },
});

const payload = await response.json();

import os
import requests
from urllib.parse import quote

phone_ref = quote("+15551234567", safe="")
response = requests.get(
    f"https://developers-api.chatmaid.net/v1/phone-numbers/{phone_ref}",
    headers={"Authorization": f"Bearer {os.environ['CHATMAID_API_KEY']}"},
)

payload = response.json()

{
  "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/status

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

Status Request Contract

Parameter	In	Type	Required	Rules
`id`	Path	`string`	Yes	Accepts phone ID or URL-encoded E.164 (example: %2B15551234567).
Required scope	-	`phone_numbers:read`	Yes	Also accepts phone-numbers:read.
Status codes	-	`200 \| 401 \| 403 \| 404 \| 429`	Yes	Typical status endpoint responses.

curl -X GET "https://developers-api.chatmaid.net/v1/phone-numbers/%2B15551234567/status" \
  -H "Authorization: Bearer sk_test_xxx"

const phoneRef = encodeURIComponent("+15551234567");
const response = await fetch(`https://developers-api.chatmaid.net/v1/phone-numbers/${phoneRef}/status`, {
  headers: { Authorization: "Bearer " + process.env.CHATMAID_API_KEY },
});

const payload = await response.json();

import os
import requests
from urllib.parse import quote

phone_ref = quote("+15551234567", safe="")
response = requests.get(
    f"https://developers-api.chatmaid.net/v1/phone-numbers/{phone_ref}/status",
    headers={"Authorization": f"Bearer {os.environ['CHATMAID_API_KEY']}"},
)

payload = response.json()

{
  "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.

Phone Numbers