> ## 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.

# Quickstart

> Confirm your token, send your first SMS, and subscribe to a webhook event.

This guide walks through your first calls against the Dialbird API. You'll need an access token — see [Authentication](/getting-started/authentication) to obtain one.

<Steps>
  <Step title="Confirm your token">
    Call `GET /me` to verify the token and inspect the granted scopes.

    ```bash theme={null}
    curl https://app-staging.dialbird.io/api/v1/me \
      -H "Authorization: Bearer $DIALBIRD_TOKEN"
    ```

    A `200` response confirms the token is valid and scoped.
  </Step>

  <Step title="Create a contact">
    At least one of `primary_phone` or `primary_email` is required. Requires the `api:contacts:write` scope.

    ```bash theme={null}
    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": "ada@example.com"
      }'
    ```

    Returns `201` with the created contact.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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!"
      }'
    ```

    <Note>
      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.
    </Note>
  </Step>

  <Step title="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.

    ```bash theme={null}
    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](/concepts/webhooks) for verifying delivery signatures.
  </Step>
</Steps>

## Next steps

<Columns cols={2}>
  <Card title="Conventions" icon="list-check" href="/concepts/conventions">
    Request and response rules that apply to every endpoint.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Receive and verify signed event deliveries.
  </Card>
</Columns>