Quickstart

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

Confirm your token

Call GET /me to verify the token and inspect the granted scopes.

curl https://app-staging.dialbird.io/api/v1/me \
  -H "Authorization: Bearer $DIALBIRD_TOKEN"

A 200 response confirms the token is valid and scoped.

Create a contact

At least one of primary_phone or primary_email is required. Requires the api:contacts:write scope.

curl -X POST https://app-staging.dialbird.io/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": "[email protected]"
  }'

Returns 201 with the created contact.

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://app-staging.dialbird.io/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.

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://app-staging.dialbird.io/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.

Getting started

Concepts

Next steps

Conventions

Webhooks

​Next steps

Conventions

Webhooks

Next steps