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.

Write endpoints (POST /contacts, POST /messages) accept an optional Idempotency-Key header so you can safely retry a request after a network error without performing the operation twice.

​
Using a key

Generate a unique key per logical operation (a UUID works well) and send it on the request. Keys can be up to 255 characters. 
curl -X POST https://api.dialbird.com/api/v1/messages \
  -H "Authorization: Bearer $DIALBIRD_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c1d9a-1b2c-4d5e-9f01-abcdef123456" \
  -d '{ "to": "+15551234567", "body": "Hello!" }'

​
Behavior

ScenarioResult
Retry with the same key and identical bodyThe original response is replayed; the operation does not run again.
Reuse the key with a different body409 idempotency_key_reused.
Retry while the first request is still in flight409 idempotency_in_progress.
Keys are retained for 24 hours. After that, the same key is treated as new.
Derive the key from a stable identifier in your own system (for example, an order id or message draft id) so retries from any part of your code reuse the same key.

​
Handling conflicts

A 409 response uses the standard error envelope. On idempotency_in_progress, wait briefly and retry the same request — the original will have completed and its response will be replayed.