ChatmaidChatmaid DevelopersChatmaid Dev
Docs
DashboardStart Building
Core API

API Reference

Endpoint-level parameters and response fields for integration APIs.

Base URL:

  • https://developers-api.chatmaid.net

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

POST /v1/messages/send

POST/v1/messages/sendAuth: API key

Create a new outbound message.

Request Contract

ParameterInTypeRequiredRules
fromPhoneIdBodystringYesMust be a phone ID in your account.
toBodystringYesE.164 format (example: +15551234567).
contentBodystringNoMax length 4096. Required if mediaUrls is empty.
mediaUrlsBodystring[]NoPublic HTTPS URLs only. Required if content is empty.
idempotencyKeyBodystringNoMax length 64. Reuse returns the original message.

Authorization and Scopes

RequirementValue
Auth headerAuthorization: Bearer sk_test_* | sk_live_*
Any required scopemessages:send
Alternative accepted scopemessages:write

Status Codes

CodeMeaning
201Message accepted.
400Validation error or phone not connected for live key.
401Missing/invalid/expired API key.
403API key does not include required scope.
404fromPhoneId not found in account.
429Rate limit exceeded for this API key.

Response Fields

FieldTypeNotes
data.idstringMessage ID (msg_*).
data.environment"test" | "live"Inferred from API key prefix.
data.statuspending|sent|delivered|read|failedInitial status is typically sent, then progresses asynchronously.
data.sentAtstring | nullSet when message is marked sent.
data.errorCodestring | nullPopulated when status is failed.
Request Example
curl -X POST https://developers-api.chatmaid.net/v1/messages/send \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"fromPhoneId":"507f1f77bcf86cd799439011","to":"+15557654321","content":"Hello"}'
Expected 201 Response
{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "content": "Hello",
    "mediaUrls": [],
    "environment": "test",
    "status": "sent",
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:33.120Z",
    "deliveredAt": null,
    "readAt": null,
    "failedAt": null,
    "errorCode": null,
    "errorMessage": null
  }
}

GET /v1/messages

GET/v1/messagesAuth: API key

Paginated list of messages for the authenticated account.

Request Contract

ParameterInTypeRequiredRules
phoneNumberIdQuerystringNoFilter by sender phone ID.
statusQuerystringNoOne of pending, sent, delivered, read, failed.
environmentQuerystringNoOne of live, test. Defaults to API key environment.
pageQuerynumberNoInteger >= 1. Default 1.
limitQuerynumberNoInteger 1..100. Default 20.

Authorization and Scopes

RequirementValue
Auth headerAuthorization: Bearer sk_test_* | sk_live_*
Required scopemessages:read

Status Codes

CodeMeaning
200Page returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
429Rate limit exceeded for this API key.

Response Fields

FieldTypeNotes
data.data[]Message[]Array sorted by createdAt desc.
data.pagination.pagenumberCurrent page index (1-based).
data.pagination.limitnumberRequested page size.
data.pagination.totalnumberTotal matching messages.
data.pagination.totalPagesnumberComputed page count.
Request Example
curl -X GET "https://developers-api.chatmaid.net/v1/messages?status=delivered&page=1&limit=20" \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "msg_abc123def456",
        "from": "+15551234567",
        "to": "+15557654321",
        "content": "Hello",
        "status": "delivered",
        "createdAt": "2026-02-06T14:18:33.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1
    }
  }
}

GET /v1/messages/:messageId

GET/v1/messages/:messageIdAuth: API key

Get one message and its lifecycle timestamps.

Request Contract

ParameterInTypeRequiredRules
messageIdPathstringYesMessage ID returned by send endpoint (msg_*).

Authorization and Scopes

RequirementValue
Auth headerAuthorization: Bearer sk_test_* | sk_live_*
Required scopemessages:read

Status Codes

CodeMeaning
200Message returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
404Message ID not found in this account.
429Rate limit exceeded for this API key.
Request Example
curl -X GET https://developers-api.chatmaid.net/v1/messages/msg_abc123def456 \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": {
    "id": "msg_abc123def456",
    "from": "+15551234567",
    "to": "+15557654321",
    "content": "Hello",
    "mediaUrls": [],
    "environment": "test",
    "status": "read",
    "errorCode": null,
    "errorMessage": null,
    "createdAt": "2026-02-06T14:18:33.000Z",
    "sentAt": "2026-02-06T14:18:33.120Z",
    "deliveredAt": "2026-02-06T14:18:34.200Z",
    "readAt": "2026-02-06T14:18:36.000Z",
    "failedAt": null
  }
}

GET /v1/phone-numbers

GET/v1/phone-numbersAuth: API key

List phone numbers available to this account.

Authorization and Scopes

RequirementValue
Auth headerAuthorization: Bearer sk_test_* | sk_live_*
Recommended scopephone_numbers:read
Backward-compatible scope acceptedphone-numbers:read

Status Codes

CodeMeaning
200Phone list returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
429Rate limit exceeded for this API key.
Request Example
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 /v1/phone-numbers/:id

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

Get one phone number by internal ID or URL-encoded E.164 value.

Request Contract

ParameterInTypeRequiredRules
idPathstringYesAccepts phone ID or URL-encoded E.164 value (example: %2B15551234567).

Status Codes

CodeMeaning
200Phone returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
404Phone reference not found in this account.
429Rate limit exceeded for this API key.
Request Example
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"
  }
}

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

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

Get live connection state by internal ID or URL-encoded E.164 value.

Request Contract

ParameterInTypeRequiredRules
idPathstringYesAccepts phone ID or URL-encoded E.164 value (example: %2B15551234567).

Status Codes

CodeMeaning
200Status returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
404Phone reference not found in this account.
429Rate limit exceeded for this API key.
Request Example
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"
  }
}

GET /v1/account

GET/v1/accountAuth: API key

Read account profile and aggregate counters.

Authorization and Scopes

RequirementValue
Auth headerAuthorization: Bearer sk_test_* | sk_live_*
Recommended scopeaccount:read
Other accepted scopesmessages:read, messages:send, messages:write

Status Codes

CodeMeaning
200Account data returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
429Rate limit exceeded for this API key.
Request Example
curl -X GET https://developers-api.chatmaid.net/v1/account \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": {
    "accountId": "acc_abc123def456",
    "name": "Acme Inc",
    "email": "developer@acme.com",
    "subscriptionStatus": "active",
    "stats": {
      "apiKeys": 2,
      "phoneNumbers": 1,
      "messages": 328
    }
  }
}

GET /v1/account/usage

GET/v1/account/usageAuth: API key

Read account usage metrics for day, week, or month.

Request Contract

ParameterInTypeRequiredRules
periodQuerystringNoOne of day, week, month. Default month.

Status Codes

CodeMeaning
200Usage returned.
401Missing/invalid/expired API key.
403API key does not include required scope.
429Rate limit exceeded for this API key.
Request Example
curl -X GET "https://developers-api.chatmaid.net/v1/account/usage?period=month" \
  -H "Authorization: Bearer sk_test_xxx"
Expected 200 Response
{
  "success": true,
  "data": {
    "period": "month",
    "startDate": "2026-01-07T14:20:00.000Z",
    "endDate": "2026-02-06T14:20:00.000Z",
    "messages": {
      "total": 328,
      "pending": 0,
      "sent": 314,
      "delivered": 306,
      "read": 298,
      "failed": 14
    },
    "apiRequests": {
      "total": 1242,
      "successful": 1221,
      "failed": 21
    }
  }
}

Response Schema

Standard Success Envelope
{
  "success": true,
  "data": {}
}
Standard Error Envelope
{
  "success": false,
  "error": "Unauthorized",
  "message": ["Invalid API key"],
  "statusCode": 401,
  "timestamp": "2026-02-06T14:22:30.000Z",
  "path": "/v1/messages"
}
Rate Limit Error Envelope
{
  "success": false,
  "error": "Rate limit exceeded",
  "retryAfter": 60
}
On This Page