Phound developer docs
Send and receive SMS from your own code, get told what happened to every message, and work with your call and meeting recordings. REST APIs, one API key.
| API | Base URL | What it covers |
|---|---|---|
| Messaging API | https://api.phound.app/messaging/v1 | Messages, conversations, contacts and suppressions. |
| Account API | https://api.phound.app/accounts/v1 | Your account and personas, phone numbers, API keys, webhooks and their delivery log, and messaging registration. |
| Recordings API | https://api.phound.app/recordings/v1 | Call and meeting recordings, their files and tags, the bin, Dropbox, and your podcast feed. |
| Calls API | https://api.phound.app/calls/v1 | Your call history, over the Phound app and the phone network, call flows and voicemail. |
All take JSON, return JSON, and authenticate every request with Authorization: Bearer <key>.
Get a key by
signing in with your Phound account.
Quickstart
From nothing to a delivered message you get notified about.
RequiredMessaging registration
Register your business for 10DLC — sending needs it approved.
GuideAuthentication
API keys, scopes, and acting for another Phound user.
GuideSending messages
Addressing, scheduling, safe retries, search, and following a message to its final status.
GuideWebhooks
Message and call events, signatures, retries and secret rotation.
GuideRecordings
Listing and downloading recordings, the bin, Dropbox, and the podcast feed.
ReferenceAll endpoints
Every API on one page, to see at a glance what they can do.
ReferenceMessaging API
Messages, conversations, contacts and suppressions.
ReferenceAccount API
Your account and personas, phone numbers, API keys, webhooks and their delivery log, and messaging registration.
ReferenceRecordings API
Call and meeting recordings, their files and tags, the bin, Dropbox, and your podcast feed.
ReferenceCalls API
Your call history, over the Phound app and the phone network, call flows and voicemail.
US carriers only deliver business texts from senders registered for 10DLC. Submit your business's
messaging registration first: until it's approved,
POST /messages answers 403 registration_required. Everything else works meanwhile.
Key concepts
- Conversations, not blasts. The unit of work is a conversation between one of your personas and one other person, whichever of its numbers is used. It is not a bulk-sending API: there are no campaigns, recipient lists or batch endpoints. Group threads are not supported in this version.
- Conversations are created for you. You never need to create one before sending. A conversation is identified by your number + the other person; sending to someone new starts one.
- One message object everywhere. The message
POST /messagesreturns is the same objectGET /messages/{id}returns, and the same object in thedataof every webhook event. - Switch on groups, not on specific values.
status.group(6 values) anderror.group(8 values) are fixed for this version. Newstatus.stateanderror.codevalues can appear within those groups at any time; treat one you don't recognise as its group. - Know what delivery you can confirm. SMS gives you at best a carrier receipt, never a read
receipt.
delivery_fidelityon every message tells you which applies.
Absent versus null
- Absent — your key lacks the scope to see the field.
null— the field is in scope but has no value.
Retention
| Data | Kept for |
|---|---|
| Webhook events and delivery attempts | 30 days |
| Idempotency keys | 24 hours |
Errors
Every error response is a Problem object (RFC 9457,
application/problem+json), the same shape in every API:
{
"type": "https://api.phound.app/messaging/v1/docs#description/validation-failed",
"title": "Request failed validation",
"status": 422,
"code": "validation_failed",
"group": "validation",
"retryable": false,
"owner_action_required": false,
"detail": "`to` must be an E.164 phone number, e.g. +14155550100.",
"errors": [ { "pointer": "/to", "code": "invalid_e164" } ]
}
- Handle errors by
group; usecodefor the specific case. retryable— retrying the identical request could succeed.owner_action_required— someone with access to the account has to fix something first.next_step, when present, says what to do.errors[]names each field at fault, by JSON Pointer.
The full catalog of codes is under Errors in each API's reference: Messaging API, Account API, Recordings API, Calls API.