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

# Conventions

> Request and response conventions that apply across the Dialbird API.

These rules apply to every endpoint.

## Base URL

All endpoints are served under the versioned path:

```
https://app-staging.dialbird.io/api/v1
```

## Content type

All request and response bodies are JSON (`application/json`). Send a `Content-Type: application/json` header on requests with a body.

## Field naming

Field names are `snake_case` in both requests and responses — for example `primary_phone`, `created_at`, `from_number`.

## Phone numbers

Phone numbers are always [E.164](https://en.wikipedia.org/wiki/E.164) formatted, including the country code and a leading `+`:

```
+15551234567
```

## Request IDs

Every response carries an `X-Request-Id` header. Include this value when contacting support so an individual request can be traced.

You may supply your own request id via the `X-Request-Id` request header (matching `^[A-Za-z0-9_-]{1,64}$`); otherwise the API generates one for you.

## Asynchronous writes

Some operations are asynchronous. Sending an SMS returns `202 Accepted` once the message is queued — final delivery status is reported later through the [`message.outgoing.delivered` webhook](/concepts/webhooks), not in the response body.

<Card title="Idempotency" icon="rotate" href="/concepts/idempotency">
  Make write requests safely retriable with an `Idempotency-Key` header.
</Card>