Phone API — SMS Messaging, Voice Calls & Inbound Logs

Every Nonhumans agent is provisioned a real phone number capable of sending and receiving SMS and initiating voice calls. The Phone API lets your agent interact with humans and services over the PSTN — useful for notifications, two-factor authentication flows, outbound outreach, and voice-driven automation. No telephony setup required.

GET /v1/phone

Returns the phone number assigned to your agent, along with its country and supported capabilities.

curl https://api.nonhumans.ai/v1/phone \
  -H "Authorization: Bearer $NONHUMANS_KEY"

Example response:

{
  "number": "+14155550192",
  "country": "US",
  "capabilities": {
    "sms": true,
    "voice": true
  }
}

string

The agent’s phone number in E.164 format (e.g. +14155550192).

string

ISO 3166-1 alpha-2 country code of the number’s origin (e.g. US, GB).

object

Object describing what the number supports.

Show Capability fields

boolean

Whether the number can send and receive SMS messages.

boolean

Whether the number can make and receive voice calls.

POST /v1/phone/sms

Send an SMS message from your agent’s number to any E.164-formatted phone number.

curl -X POST https://api.nonhumans.ai/v1/phone/sms \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12025550147",
    "message": "Hi! Your order has been confirmed. Reply STOP to unsubscribe."
  }'

string

required

Recipient phone number in E.164 format (e.g. +12025550147).

string

required

The text content of the SMS. Messages over 160 characters are automatically segmented into multiple parts.

Example response:

{
  "message_id": "sms_01HXYZ456",
  "status": "queued"
}

string

Unique identifier for the SMS message. Use this to track delivery status.

string

Initial delivery status. One of queued, sent, delivered, or failed.

Delivery status transitions from queued → sent → delivered asynchronously. Poll the message status or configure a webhook to receive real-time delivery updates.

GET /v1/phone/messages

List inbound SMS messages received by your agent’s number. Messages are returned in reverse chronological order.

curl "https://api.nonhumans.ai/v1/phone/messages?limit=20" \
  -H "Authorization: Bearer $NONHUMANS_KEY"

integer

Number of messages to return. Default 20, max 100.

string

Pagination cursor from a previous response’s next_cursor.

string (ISO 8601)

Only return messages received after this timestamp.

Example response:

{
  "messages": [
    {
      "id": "sms_01HINB001",
      "from": "+12025550147",
      "to": "+14155550192",
      "body": "Thanks for the update!",
      "received_at": "2024-12-01T16:22:00Z"
    }
  ],
  "next_cursor": null
}

array

Array of inbound SMS message objects.

Show Message fields

string

Unique message identifier.

string

Sender’s phone number in E.164 format.

string

Your agent’s phone number.

string

Full text content of the received SMS.

string (ISO 8601)

Timestamp when the message was received.

POST /v1/phone/calls

Initiate an outbound voice call from your agent’s number. You can provide a script for text-to-speech or a URL pointing to a TwiML document for programmatic call flow control.

curl -X POST https://api.nonhumans.ai/v1/phone/calls \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12025550147",
    "script": "Hello! This is a reminder that your appointment is tomorrow at 2pm. Press 1 to confirm."
  }'

string

required

The phone number to call, in E.164 format.

string

Text-to-speech script the agent will speak when the call connects. Either script or twiml_url is required.

string

URL of a TwiML document to drive the call flow. Use this for interactive calls, recordings, or branching logic. Either script or twiml_url is required.

Example response:

{
  "call_id": "call_01HXYZ789",
  "status": "initiated"
}

string

Unique identifier for the voice call. Use this to track call progress.

string

Initial call status. One of initiated, ringing, in-progress, completed, or failed.

Calls to certain regions may require regulatory compliance (e.g. caller ID registration or DNC list checks). Ensure your use case complies with local telecommunications laws before initiating outbound calls.

Overview

Endpoints

Phone API — SMS Messaging, Voice Calls & Inbound Logs

GET /v1/phone

POST /v1/phone/sms

GET /v1/phone/messages

POST /v1/phone/calls

​GET /v1/phone

​POST /v1/phone/sms

​GET /v1/phone/messages

​POST /v1/phone/calls

GET /v1/phone

POST /v1/phone/sms

GET /v1/phone/messages

POST /v1/phone/calls