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.

APIBase URLWhat it covers
Messaging APIhttps://api.phound.app/messaging/v1Messages, conversations, contacts and suppressions.
Account APIhttps://api.phound.app/accounts/v1Your account and personas, phone numbers, API keys, webhooks and their delivery log, and messaging registration.
Recordings APIhttps://api.phound.app/recordings/v1Call and meeting recordings, their files and tags, the bin, Dropbox, and your podcast feed.
Calls APIhttps://api.phound.app/calls/v1Your 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.

Sending needs an approved registration

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 /messages returns is the same object GET /messages/{id} returns, and the same object in the data of every webhook event.
  • Switch on groups, not on specific values. status.group (6 values) and error.group (8 values) are fixed for this version. New status.state and error.code values 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_fidelity on 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

DataKept for
Webhook events and delivery attempts30 days
Idempotency keys24 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; use code for 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.