Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dialbird.io/llms.txt

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

This guide walks through your first calls against the Dialbird API. You’ll need an access token — see Authentication to obtain one.
1

Confirm your token

Call GET /me to verify the token and inspect the granted scopes.
curl https://api.dialbird.com/api/v1/me \
  -H "Authorization: Bearer $DIALBIRD_TOKEN"
A 200 response confirms the token is valid and scoped.
2

Create a contact

At least one of primary_phone or primary_email is required. Requires the api:contacts:write scope.
curl -X POST https://api.dialbird.com/api/v1/contacts \
  -H "Authorization: Bearer $DIALBIRD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contact-ada-001" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "primary_phone": "+15551234567",
    "primary_email": "ada@example.com"
  }'
Returns 201 with the created contact.
3

Send an SMS

Sends a single text message. The send is asynchronous — the API returns 202 Accepted once queued. Requires the api:messages:write scope.
curl -X POST https://api.dialbird.com/api/v1/messages \
  -H "Authorization: Bearer $DIALBIRD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: msg-hello-001" \
  -d '{
    "to": "+15551234567",
    "body": "Hello from the Dialbird API!"
  }'
If your business has multiple phone numbers, include from (E.164) to choose the sender. With a single number, from defaults to your primary number.
4

Subscribe to an event

Subscribe a URL to a single event type. The response includes the signing_secret once — store it immediately. Requires the api:webhooks scope.
curl -X POST https://api.dialbird.com/api/v1/subscriptions \
  -H "Authorization: Bearer $DIALBIRD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "message.outgoing.delivered",
    "target_url": "https://example.com/hooks/dialbird"
  }'
Final SMS delivery status arrives at your target_url via the message.outgoing.delivered webhook. See Webhooks for verifying delivery signatures.

​
Next steps

Conventions

Request and response rules that apply to every endpoint.

Webhooks

Receive and verify signed event deliveries.