Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nonhumans.ai/llms.txt

Use this file to discover all available pages before exploring further.

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
  }
}
​
number
string
The agent’s phone number in E.164 format (e.g. +14155550192).
​
country
string
ISO 3166-1 alpha-2 country code of the number’s origin (e.g. US, GB).
​
capabilities
object
Object describing what the number supports.

​
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."
  }'
​
to
string
required
Recipient phone number in E.164 format (e.g. +12025550147).
​
message
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"
}
​
message_id
string
Unique identifier for the SMS message. Use this to track delivery status.
​
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"
​
limit
integer
Number of messages to return. Default 20, max 100.
​
cursor
string
Pagination cursor from a previous response’s next_cursor.
​
since
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
}
​
messages
array
Array of inbound SMS message objects.

​
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."
  }'
​
to
string
required
The phone number to call, in E.164 format.
​
script
string
Text-to-speech script the agent will speak when the call connects. Either script or twiml_url is required.
​
twiml_url
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"
}
​
call_id
string
Unique identifier for the voice call. Use this to track call progress.
​
status
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.