​
Response Format

​
iMessage endpoints (/v1/*)

Every /v1 response is JSON and includes an ok field indicating success or failure. Success Response: 
{
  "ok": true,
  ...endpoint-specific fields
}
Error Response: 
{
  "ok": false,
  "error": "Description of what went wrong"
}
The endpoint-specific fields sit at the top level of the response alongside ok (for example threads, messages, or thread_id) — there is no nested data envelope. 
import requests

response = requests.get(
    'https://sms.phones.inc/v1/threads',
    headers={'API-KEY': 'sk_your_api_key'}
)

data = response.json()

if data['ok']:
    for thread in data['threads']:
        print(thread['address'], thread['last_text'])
else:
    print('Error:', data['error'])

​
SMS rental endpoints (/sms/*)

The rental endpoints use a slightly different shape:
  • POST /sms/rent returns a plain JSON object on success (number, cost, service, transaction_id) with no ok field. Errors are {"error": "..."} with a non-200 status.
  • GET /sms/code returns the verification code as a plain text body, not JSON.
  • POST /sms/cancel returns {"ok": true} on success.
Always check the HTTP status code on /sms/* endpoints before parsing the body.

​
HTTP Status Codes

CodeMeaning
200Success
201Created (new key or webhook)
202Accepted — the message was queued for sending
400Bad Request (missing or invalid parameters)
401Unauthorized (invalid or missing API key)
402Payment Required (insufficient credits for a message send or number rental — see Pricing)
403Forbidden (no sending number assigned to your account, or from is not one of your numbers)
404Not Found (unknown thread, key, webhook, or transaction)
409Conflict (no rental numbers available, or code not received yet)
500Internal Server Error
502Upstream rental service temporarily unavailable
503Number rental is not configured on this deployment

​
Asynchronous Sending

Sending a message returns 202 Accepted with "status": "queued" — the message is durably queued and delivered as soon as possible. Delivery normally completes within a few seconds. To observe the result, read the thread history with GET /v1/threads/{id}/messages; your sent message appears there with from_me: true once delivered. The send charge is debited when the request is accepted and refunded automatically if delivery fails — see Pricing.