Docs / Get started

Quickstart

Six short steps from nothing to a delivered SMS that your server is told about. Every request here is one you can paste into a terminal.

0. Get an API key

Sign in to the dashboard with your Phound account — there is no separate developer account — and create a key on the API keys page. For this guide it needs the numbers:read, messages:send and webhooks:manage scopes.

The key looks like ck_live_… and is shown once. Every request sends it as Authorization: Bearer <key>.

export PHOUND_KEY=ck_live_...
Register your business first

Sending needs an approved 10DLC registration — US carriers only deliver business texts from registered senders. Submit it on the dashboard's Registration page now: review usually takes a few business days, and you can do steps 1–3 meanwhile. Until it's approved, step 4 answers 403 registration_required. More about registration

No server yet?

The dashboard has a built-in webhook inbox. On Webhooks, choose Use the built-in inbox, and every event lands on the Events page with its signature checked. You can skip steps 2 and 3 until you have an endpoint of your own.

1. Pick the number to send from

Your numbers live in the Account API. Ask for the ones that can send SMS:

curl "https://api.phound.app/accounts/v1/phone-numbers?capability=sms" \
  -H "Authorization: Bearer $PHOUND_KEY"
{ "object": "list", "has_more": false, "next_cursor": null,
  "data": [ { "id": "pn_219552", "e164": "+13075222720",
              "capabilities": ["voice", "sms", "mms"], "status": "active" } ] }

The e164 is what you send from in step 4 — anywhere a number is taken, the number itself is how you name it (the id works too).

2. Register a webhook

Tell us where to send events. Your endpoint must be public HTTPS. Webhooks are managed in the Account API.

curl https://api.phound.app/accounts/v1/webhooks \
  -H "Authorization: Bearer $PHOUND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/phound/webhooks", "events": ["message.*"]}'

message.* subscribes to every message event: message.received for replies and other incoming messages, and the delivery events that follow the messages you send. To pick individual events, list them instead, for example ["message.received", "message.failed"].

The secret is shown once

The response includes secret (whsec_…). It is never returned again, so store it now: you need it to verify every event.

Your endpoint must answer 2xx within 10 seconds. Anything else is retried with backoff for about three days — see Webhooks.

3. Verify the signature on every event

Events are signed per the Standard Webhooks spec, so any Standard Webhooks library can verify them. Or, in a few lines of Python:

import base64, hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes) -> bool:
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:  # reject replays older than 5 minutes
        return False
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    # The header may carry several signatures (during a secret rotation).
    return any(
        hmac.compare_digest(sig, expected)
        for version, _, sig in (s.partition(",") for s in headers["webhook-signature"].split())
        if version == "v1"
    )

Pass body as the raw bytes you received. Parsing the JSON and serialising it again changes the bytes, and the check fails. Webhooks has the same check in Node.js and Go.

To check your endpoint before sending anything real, ask for a test event. It is signed like a real one and carries data.test: true:

curl -X POST https://api.phound.app/accounts/v1/webhooks/wh_.../test \
  -H "Authorization: Bearer $PHOUND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "message.sent"}'

The response shows exactly what was sent and what your endpoint answered: status, headers, body and timing.

4. Send a message

curl https://api.phound.app/messaging/v1/messages \
  -H "Authorization: Bearer $PHOUND_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2d0e-order-4471-shipped" \
  -d '{"from": "+13075222720", "to": "+14155550123",
       "text": "Hi Maria, your order has shipped."}'

to is an E.164 number, with the leading +. The Idempotency-Key is any unique string you choose per message: if the request times out, retry with the same key and you get the original result back rather than a second text on someone's phone.

A 202 means the carrier accepted it:

{ "id": "msg_01m3ae8f0pxc3xn1m8pbdt68gp", "object": "message",
  "from": "+13075222720", "to": "+14155550123", "channel": "sms",
  "status": { "group": "sent", "state": "sent", "final": false, "sequence": 2 } }

A 422 means it was refused before anything was sent. The body says why: code (for example from_not_owned), a readable detail, and in errors[] the field at fault.

5. Follow it to the end

Your webhook receives message.sent right away, then exactly one final event:

Eventstatus.stateMeaning
message.delivereddelivered_to_carrier The recipient's carrier confirmed delivery.
message.unconfirmeddelivery_unconfirmed No receipt came back within 5 minutes. Many carriers never send one; the message most likely arrived — not a failure.
message.faileddelivery_failed The carrier reported it undeliverable; see error.
message.rejectedrejected, suppressed or sending_failed Refused — for example the recipient opted out — or couldn't be handed to the carrier; see error.

Events can arrive out of order and more than once. Deduplicate on the webhook-id header, and ignore an event whose sequence is not higher than the last one you stored for that message.

You can also look a message up at any time with GET /messages/{id}. If events stop arriving, GET /webhooks/{id}/deliveries?succeeded=false shows every failed attempt with your endpoint's response, and POST /webhook-deliveries/{id}/retry sends one again.

Where next