{ "item": [ { "id": "37cee47b-9cd5-86e6-8394-423def22a8e4", "name": "email-messages", "description": { "content": "Send emails to recipients you address explicitly in `to`, `cc`, and `bcc`. Use this for transactional sends (receipts, password resets, alerts) and for marketing sends where you already have the recipient addresses on hand. The same endpoint accepts every content type. Set `category` to control suppression policy.\n", "type": "text/plain" }, "item": [ { "id": "37987648-2686-838f-85bb-2529dd5b4982", "name": "Create an email message", "request": { "name": "Create an email message", "description": { "content": "Sends an email to the recipients you list explicitly in `to`/`cc`/`bcc`. Use it for\ntransactional sends (receipts, password resets, alerts) and for marketing sends where\nyou have the recipient addresses on hand. To submit many independent messages in one\nrequest, use [Create a batch of email messages](https://bird.com/docs/api/reference/create-email-message-batch)\ninstead. The `category` field controls suppression policy independently of content:\nset it to `marketing` when sending marketing content.\n\nThe `202` response means the message is safely accepted and awaiting delivery.\nFetch it by `id` or subscribe to webhook events to follow delivery. The\nrequest never half-succeeds: an unverified sender domain or any field-level\nvalidation failure rejects it immediately with a `422` naming the reason.\nSuppression is evaluated per recipient after acceptance, so a suppressed recipient\nappears as `rejected` on the message's recipient list rather than as a synchronous\nerror. New workspaces can send from the shared onboarding domain before verifying\ntheir own. The [quickstart](https://bird.com/docs/get-started/send-your-first-email) covers its\nrecipient and volume limits.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/email/messages" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"email\": \"noreply@acme.com\",\n \"name\": \"Acme Support\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\",\n \"name\": \"Jane Doe\"\n }\n ],\n \"cc\": [\n \"manager@acme.com\"\n ],\n \"reply_to\": [\n \"support@acme.com\"\n ],\n \"subject\": \"Welcome aboard\",\n \"html\": \"

Hi there 👋

\",\n \"text\": \"Hi there\",\n \"headers\": {\n \"X-Campaign\": \"spring-2026\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"metadata\": {\n \"user_id\": \"usr_12345\"\n },\n \"category\": \"transactional\",\n \"track_clicks\": false\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "f6d46c0b-9609-8764-8c25-f2bad1543cfc", "name": "Message accepted for asynchronous delivery.", "originalRequest": { "name": "Create an email message", "description": { "content": "Sends an email to the recipients you list explicitly in `to`/`cc`/`bcc`. Use it for\ntransactional sends (receipts, password resets, alerts) and for marketing sends where\nyou have the recipient addresses on hand. To submit many independent messages in one\nrequest, use [Create a batch of email messages](https://bird.com/docs/api/reference/create-email-message-batch)\ninstead. The `category` field controls suppression policy independently of content:\nset it to `marketing` when sending marketing content.\n\nThe `202` response means the message is safely accepted and awaiting delivery.\nFetch it by `id` or subscribe to webhook events to follow delivery. The\nrequest never half-succeeds: an unverified sender domain or any field-level\nvalidation failure rejects it immediately with a `422` naming the reason.\nSuppression is evaluated per recipient after acceptance, so a suppressed recipient\nappears as `rejected` on the message's recipient list rather than as a synchronous\nerror. New workspaces can send from the shared onboarding domain before verifying\ntheir own. The [quickstart](https://bird.com/docs/get-started/send-your-first-email) covers its\nrecipient and volume limits.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/email/messages" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": {\n \"email\": \"noreply@acme.com\",\n \"name\": \"Acme Support\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\",\n \"name\": \"Jane Doe\"\n }\n ],\n \"cc\": [\n \"manager@acme.com\"\n ],\n \"reply_to\": [\n \"support@acme.com\"\n ],\n \"subject\": \"Welcome aboard\",\n \"html\": \"

Hi there 👋

\",\n \"text\": \"Hi there\",\n \"headers\": {\n \"X-Campaign\": \"spring-2026\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"metadata\": {\n \"user_id\": \"usr_12345\"\n },\n \"category\": \"transactional\",\n \"track_clicks\": false\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"em_01krdgeqcxet5s7t44vh8rt9mg\",\n \"from\": {\n \"email\": \"onboarding@messagebird.dev\",\n \"name\": \"Bird\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\"\n }\n ],\n \"subject\": \"Hello from Bird\",\n \"category\": \"transactional\",\n \"status\": \"accepted\",\n \"accepted_count\": 1,\n \"processed_count\": 0,\n \"delivered_count\": 0,\n \"bounced_count\": 0,\n \"complained_count\": 0,\n \"deferred_count\": 0,\n \"rejected_count\": 0,\n \"open_count\": 0,\n \"click_count\": 0,\n \"track_opens\": false,\n \"track_clicks\": false,\n \"created_at\": \"2026-07-01T12:00:00Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "dcf55993-bfbf-8faf-8d39-2517df90203f", "name": "List messages", "request": { "name": "List messages", "description": { "content": "Returns the workspace's sent and scheduled messages, newest first, as a cursor page. Each item has the aggregate delivery `status` and per-state recipient counts. Message bodies are omitted.\n\nCombine filters to narrow the page:\n\n- Delivery status.\n- Category.\n- Tag.\n- An exact `to` or `from` address.\n- A `created_after` or `created_before` time window.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "created_after", "value": "2026-05-01T00:00:00Z", "description": "Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": false, "key": "created_before", "value": "2026-06-01T00:00:00Z", "description": "Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": true, "key": "status", "value": "", "description": "Filter by aggregate delivery status." }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "category", "value": "", "description": "Filter by category." }, { "disabled": false, "key": "to", "value": "delivered@messagebird.dev", "description": "Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message. The address is normalized to lowercase before comparison.\n" }, { "disabled": false, "key": "from", "value": "noreply@acme.com", "description": "Filter by sender address. Exact match against the message `from` field. The address is normalized to lowercase before comparison.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/email/messages?limit=25&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&to=delivered@messagebird.dev&from=noreply@acme.com" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "71d76815-caf0-827c-8d0c-bc66fc6336be", "name": "Paginated list of messages.", "originalRequest": { "name": "List messages", "description": { "content": "Returns the workspace's sent and scheduled messages, newest first, as a cursor page. Each item has the aggregate delivery `status` and per-state recipient counts. Message bodies are omitted.\n\nCombine filters to narrow the page:\n\n- Delivery status.\n- Category.\n- Tag.\n- An exact `to` or `from` address.\n- A `created_after` or `created_before` time window.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "created_after", "value": "2026-05-01T00:00:00Z", "description": "Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": false, "key": "created_before", "value": "2026-06-01T00:00:00Z", "description": "Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": true, "key": "status", "value": "", "description": "Filter by aggregate delivery status." }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "category", "value": "", "description": "Filter by category." }, { "disabled": false, "key": "to", "value": "delivered@messagebird.dev", "description": "Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message. The address is normalized to lowercase before comparison.\n" }, { "disabled": false, "key": "from", "value": "noreply@acme.com", "description": "Filter by sender address. Exact match against the message `from` field. The address is normalized to lowercase before comparison.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/email/messages?limit=25&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&to=delivered@messagebird.dev&from=noreply@acme.com" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"em_01krdgeqcxet5s7t44vh8rt9mg\",\n \"from\": {\n \"email\": \"onboarding@messagebird.dev\",\n \"name\": \"Bird\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\"\n }\n ],\n \"subject\": \"Hello from Bird\",\n \"category\": \"marketing\",\n \"status\": \"accepted\",\n \"broadcast_id\": \"eb_01krdgeqcxet5s7t44vh8rt9mg\",\n \"accepted_count\": 1,\n \"processed_count\": 0,\n \"delivered_count\": 0,\n \"bounced_count\": 0,\n \"complained_count\": 0,\n \"deferred_count\": 0,\n \"rejected_count\": 0,\n \"open_count\": 0,\n \"click_count\": 0,\n \"track_opens\": false,\n \"track_clicks\": false,\n \"created_at\": \"2026-07-01T12:00:00Z\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "560de48a-0e7a-8580-846b-d0521182bb6f", "name": "Create a batch of email messages", "request": { "name": "Create a batch of email messages", "description": { "content": "Accepts up to 100 independent email messages and queues them for delivery. All items are validated before any are queued: if one fails validation, the entire batch is rejected. Field-level validation failures and business-rule failures, such as sending from a domain that is not verified, both return `422`. An item can set `scheduled_at` to send it later, on the same terms as a single scheduled send, and one batch can mix scheduled and immediate messages. Cancel a scheduled item before it sends with [Cancel an email message](https://bird.com/docs/api/reference/cancel-email-message). Suppression is evaluated per recipient after acceptance, never as a synchronous error. The `202` response returns one entry per message in submission order, each with its own `id` you can use to fetch that message or match it against webhook events. Attachments are allowed per message. Each message must stay within the 20 MB estimated generated message-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "batches" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/email/batches" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"messages\": [\n {\n \"from\": {\n \"email\": \"noreply@acme.com\",\n \"name\": \"Acme Support\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\",\n \"name\": \"Jane Doe\"\n }\n ],\n \"subject\": \"Your receipt for order #1234\",\n \"text\": \"Thanks for your purchase! Your receipt is attached.\"\n },\n {\n \"from\": {\n \"email\": \"noreply@acme.com\",\n \"name\": \"Acme Support\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\",\n \"name\": \"John Roe\"\n }\n ],\n \"subject\": \"Your receipt for order #1235\",\n \"text\": \"Thanks for your purchase! Your receipt is attached.\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "be771830-4cc0-89be-826a-9b2ceb81042b", "name": "Batch accepted for asynchronous delivery.", "originalRequest": { "name": "Create a batch of email messages", "description": { "content": "Accepts up to 100 independent email messages and queues them for delivery. All items are validated before any are queued: if one fails validation, the entire batch is rejected. Field-level validation failures and business-rule failures, such as sending from a domain that is not verified, both return `422`. An item can set `scheduled_at` to send it later, on the same terms as a single scheduled send, and one batch can mix scheduled and immediate messages. Cancel a scheduled item before it sends with [Cancel an email message](https://bird.com/docs/api/reference/cancel-email-message). Suppression is evaluated per recipient after acceptance, never as a synchronous error. The `202` response returns one entry per message in submission order, each with its own `id` you can use to fetch that message or match it against webhook events. Attachments are allowed per message. Each message must stay within the 20 MB estimated generated message-size cap, and the serialized JSON request body for the whole batch has a hard 20 MB cap.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "batches" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/email/batches" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"messages\": [\n {\n \"from\": {\n \"email\": \"noreply@acme.com\",\n \"name\": \"Acme Support\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\",\n \"name\": \"Jane Doe\"\n }\n ],\n \"subject\": \"Your receipt for order #1234\",\n \"text\": \"Thanks for your purchase! Your receipt is attached.\"\n },\n {\n \"from\": {\n \"email\": \"noreply@acme.com\",\n \"name\": \"Acme Support\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\",\n \"name\": \"John Roe\"\n }\n ],\n \"subject\": \"Your receipt for order #1235\",\n \"text\": \"Thanks for your purchase! Your receipt is attached.\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"em_01krdgeqcxet5s7t44vh8rt9mg\",\n \"status\": \"accepted\",\n \"category\": \"marketing\",\n \"requested_language\": \"pt-BR\",\n \"resolved_language\": \"pt-BR\",\n \"template_id\": \"emt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_version_id\": \"emv_01krdgeqcxet5s7t44vh8rt9mg\"\n },\n {\n \"id\": \"em_01krdgeqcxet5s7t44vh8rt9mh\",\n \"status\": \"accepted\",\n \"category\": \"transactional\",\n \"scheduled_at\": \"2026-05-22T09:00:00Z\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3908ee31-09cb-878c-8143-96c7e246ac3a", "name": "Get a message", "request": { "name": "Get a message", "description": { "content": "Returns a single message with its aggregate delivery `status` and per-state recipient counts. The response never includes the `html`/`text` bodies. When content storage is enabled for the send, fetch the stored bodies with [Get stored message content](https://bird.com/docs/api/reference/get-email-message-content). Per-recipient statuses and the event timeline are separate sub-resources.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message to fetch. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "3aeaea40-118a-809c-85e1-acd497eedd87", "name": "Message object.", "originalRequest": { "name": "Get a message", "description": { "content": "Returns a single message with its aggregate delivery `status` and per-state recipient counts. The response never includes the `html`/`text` bodies. When content storage is enabled for the send, fetch the stored bodies with [Get stored message content](https://bird.com/docs/api/reference/get-email-message-content). Per-recipient statuses and the event timeline are separate sub-resources.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message to fetch. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"em_01krdgeqcxet5s7t44vh8rt9mg\",\n \"from\": {\n \"email\": \"onboarding@messagebird.dev\",\n \"name\": \"Bird\"\n },\n \"to\": [\n {\n \"email\": \"delivered@messagebird.dev\"\n }\n ],\n \"subject\": \"Hello from Bird\",\n \"category\": \"marketing\",\n \"status\": \"accepted\",\n \"broadcast_id\": \"eb_01krdgeqcxet5s7t44vh8rt9mg\",\n \"accepted_count\": 1,\n \"processed_count\": 0,\n \"delivered_count\": 0,\n \"bounced_count\": 0,\n \"complained_count\": 0,\n \"deferred_count\": 0,\n \"rejected_count\": 0,\n \"open_count\": 0,\n \"click_count\": 0,\n \"track_opens\": false,\n \"track_clicks\": false,\n \"created_at\": \"2026-07-01T12:00:00Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "019928e3-5025-83b9-8f0e-091619323d09", "name": "Cancel a scheduled message", "request": { "name": "Cancel a scheduled message", "description": { "content": "Cancels a message that was scheduled with `scheduled_at` before it sends. Only a message that is still scheduled can be canceled. A message that already started sending, was delivered, or was previously canceled returns a conflict error. The message's status becomes `canceled` and an `email.canceled` webhook event fires. Canceling does not return consumed scheduled-send quota.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "cancel" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the scheduled message to cancel, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/cancel" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "response": [ { "id": "5f5a96e4-796e-821f-8d6b-aaf4def41cd1", "name": "The message is canceled and no longer eligible to send.", "originalRequest": { "name": "Cancel a scheduled message", "description": { "content": "Cancels a message that was scheduled with `scheduled_at` before it sends. Only a message that is still scheduled can be canceled. A message that already started sending, was delivered, or was previously canceled returns a conflict error. The message's status becomes `canceled` and an `email.canceled` webhook event fires. Canceling does not return consumed scheduled-send quota.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "cancel" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the scheduled message to cancel, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/cancel" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "status": "No Content", "code": 204, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f5e8b315-f1d2-832b-86cb-868cc4434ebe", "name": "List recipients of a message", "request": { "name": "List recipients of a message", "description": { "content": "Returns the message's per-recipient delivery state as a cursor page: each entry is\none `to`/`cc`/`bcc` recipient with its role, current `status`, rejection or bounce\ndetail when delivery failed, and open/click counts. Use it to see which specific\naddresses failed when the aggregate message `status` is mixed (for example\n`partial_failure`).\n\nThis works for every email message, including one a broadcast sent. A broadcast\nrecords one message per recipient, so such a message has exactly one recipient\nhere: the address its copy went to.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "recipients" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose recipients to list. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/recipients?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "29b66340-809b-8157-8c64-ecdb8e3ad791", "name": "Paginated list of recipients for this message.", "originalRequest": { "name": "List recipients of a message", "description": { "content": "Returns the message's per-recipient delivery state as a cursor page: each entry is\none `to`/`cc`/`bcc` recipient with its role, current `status`, rejection or bounce\ndetail when delivery failed, and open/click counts. Use it to see which specific\naddresses failed when the aggregate message `status` is mixed (for example\n`partial_failure`).\n\nThis works for every email message, including one a broadcast sent. A broadcast\nrecords one message per recipient, so such a message has exactly one recipient\nhere: the address its copy went to.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "recipients" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose recipients to list. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/recipients?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"er_01krdgeqcxet5s7t44vh8rt9mg\",\n \"parent_id\": \"em_01krdgeqcxet5s7t44vh8rt9mg\",\n \"role\": \"to\",\n \"recipient\": \"delivered@messagebird.dev\",\n \"status\": \"accepted\",\n \"rejection_reason\": \"recipient_suppressed\",\n \"bounce_type\": \"hard\",\n \"bounce_code\": \"550\",\n \"bounce_description\": \"5.1.1 Unknown user\",\n \"open_count\": 0,\n \"click_count\": 0\n }\n ],\n \"next\": [\n {\n \"kind\": \"operation\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "48ca54ff-35e6-8c02-8b85-9c141626cf8c", "name": "List events for a message", "request": { "name": "List events for a message", "description": { "content": "Returns the message's per-recipient event timeline, oldest first, as a cursor page. Lifecycle, failure, and engagement events interleave as they happen, and engagement events (`email.opened`, `email.clicked`) can repeat per recipient. Filter to one event type with `type`. For each recipient's current state rather than its history, use [List recipients of a message](https://bird.com/docs/api/reference/list-email-message-recipients).\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": true, "key": "type", "value": "", "description": "Filter by event type, for example `email.bounced` or `email.opened`." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose timeline to read. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/events?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "461dbc1d-3e37-8992-8dde-83260440d256", "name": "Paginated event timeline for this message.", "originalRequest": { "name": "List events for a message", "description": { "content": "Returns the message's per-recipient event timeline, oldest first, as a cursor page. Lifecycle, failure, and engagement events interleave as they happen, and engagement events (`email.opened`, `email.clicked`) can repeat per recipient. Filter to one event type with `type`. For each recipient's current state rather than its history, use [List recipients of a message](https://bird.com/docs/api/reference/list-email-message-recipients).\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": true, "key": "type", "value": "", "description": "Filter by event type, for example `email.bounced` or `email.opened`." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose timeline to read. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/events?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"ev_01krdgeqcxet5s7t44vh8rt9mg\",\n \"type\": \"email.delivered\",\n \"occurred_at\": \"2026-07-01T12:00:03Z\",\n \"recipient_id\": \"er_01krdgeqcxet5s7t44vh8rt9mg\",\n \"bounce_type\": \"hard\",\n \"bounce_code\": \"5.1.1\",\n \"rejection_reason\": \"recipient_suppressed\",\n \"link_name\": \"Faster exports, docs\",\n \"country\": \"US\"\n }\n ],\n \"next\": [\n {\n \"kind\": \"operation\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "ff3a464c-b542-8d89-8cf7-53f37d342fe0", "name": "Get stored message content", "request": { "name": "Get stored message content", "description": { "content": "Returns the stored HTML and text bodies for a sent message. Content storage must be enabled for the message. Content is available for up to 30 days after sending. A broadcast stores no body, so a copy the send has recorded always answers `404`, whatever the workspace has configured. A `404` indicates no content was stored for this message. A scheduled send of a workspace template, rather than a built-in one, stores its content when it sends, so it answers `404` until then. A `425` indicates the content is still being stored and the request can be retried shortly. A `410` indicates the content was stored but has since expired.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "content" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose stored content to fetch. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/content" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "297dd31b-4930-86c2-8617-a1bbe8d21ad8", "name": "Stored message content.", "originalRequest": { "name": "Get stored message content", "description": { "content": "Returns the stored HTML and text bodies for a sent message. Content storage must be enabled for the message. Content is available for up to 30 days after sending. A broadcast stores no body, so a copy the send has recorded always answers `404`, whatever the workspace has configured. A `404` indicates no content was stored for this message. A scheduled send of a workspace template, rather than a built-in one, stores its content when it sends, so it answers `404` until then. A `425` indicates the content is still being stored and the request can be retried shortly. A `410` indicates the content was stored but has since expired.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "content" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose stored content to fetch. A broadcast records one message per recipient, and [List email messages](/docs/api/reference/list-email-messages) returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/content" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"html\": \"

Hi Jane,

Your order #1234 has shipped and is on its way.

\",\n \"text\": \"Hi Jane,\\n\\nYour order #1234 has shipped and is on its way.\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "80feaca7-8d07-8996-8e76-2017aa52203f", "name": "Get a message attachment", "request": { "name": "Get a message attachment", "description": { "content": "Downloads the raw bytes of one attachment from a sent message, returned with the attachment's own content type and a Content-Disposition header that includes its filename. The message must have content storage enabled and the attachment is available for up to 30 days after sending. A `404` indicates the message has no stored content or no attachment with this ID. A `425` indicates the attachment is still being stored and the request can be retried shortly. A `410` indicates the attachment was stored but has since expired.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "attachments", ":attachment_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message the attachment belongs to, from the send response's `id` field." }, { "disabled": false, "type": "any", "value": "", "key": "attachment_id", "description": "(Required) Attachment ID, as returned in the message's `attachments` list." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/attachments/:attachment_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "e62822b8-166f-838a-8261-90aa43592509", "name": "The raw attachment bytes.", "originalRequest": { "name": "Get a message attachment", "description": { "content": "Downloads the raw bytes of one attachment from a sent message, returned with the attachment's own content type and a Content-Disposition header that includes its filename. The message must have content storage enabled and the attachment is available for up to 30 days after sending. A `404` indicates the message has no stored content or no attachment with this ID. A `425` indicates the attachment is still being stored and the request can be retried shortly. A `410` indicates the attachment was stored but has since expired.\n", "type": "text/plain" }, "url": { "path": [ "v1", "email", "messages", ":message_id", "attachments", ":attachment_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message the attachment belongs to, from the send response's `id` field." }, { "disabled": false, "type": "any", "value": "", "key": "attachment_id", "description": "(Required) Attachment ID, as returned in the message's `attachments` list." } ], "raw": "{{BIRD_API_URL}}/v1/email/messages/:message_id/attachments/:attachment_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "Has the attachment's filename. The value is `attachment` for regular files, or `inline` for inline images referenced from the HTML body.\n", "key": "Content-Disposition", "value": "" }, { "key": "Content-Type", "value": "application/octet-stream" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "6ee1264f-6de1-8dac-8307-30c4ac068d10", "name": "email-contacts", "description": { "content": "Contacts are the people you send broadcasts to. Each contact is unique by email address within a workspace and carries optional name fields and custom properties for personalization. Custom properties are defined once per workspace via the contact properties API and then set per contact.\n", "type": "text/plain" }, "item": [ { "id": "72289e58-2ec8-8b5f-8f87-87fea5df989c", "name": "Create a contact", "request": { "name": "Create a contact", "description": { "content": "Creates a contact in the workspace, identified by an email address, a phone number, or both; at least one is required. Email is stored trimmed and lowercased, and phone in its canonical international form. Creating a second contact with the same email or phone number, or reusing another contact's `external_id`, returns a conflict error.\n\nTo create or update many contacts in one request, or to write a contact without knowing whether the address already exists, use [Create or update contacts in bulk](https://bird.com/docs/api/reference/create-contact-batch) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contacts" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"first_name\": \"Alice\",\n \"last_name\": \"Anderson\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "64d09593-69b6-86ca-85cd-be6224ef99a8", "name": "Contact created.", "originalRequest": { "name": "Create a contact", "description": { "content": "Creates a contact in the workspace, identified by an email address, a phone number, or both; at least one is required. Email is stored trimmed and lowercased, and phone in its canonical international form. Creating a second contact with the same email or phone number, or reusing another contact's `external_id`, returns a conflict error.\n\nTo create or update many contacts in one request, or to write a contact without knowing whether the address already exists, use [Create or update contacts in bulk](https://bird.com/docs/api/reference/create-contact-batch) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contacts" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"first_name\": \"Alice\",\n \"last_name\": \"Anderson\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"con_01krdgeqcxet5s7t44vh8rt9mg\",\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"audiences\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\"\n }\n ],\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "9484d7b7-a0cc-88eb-8e9f-8800d3715b03", "name": "List contacts", "request": { "name": "List contacts", "description": { "content": "Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact `email`, `phone_number`, or `external_id`, or search by email, first name, last name, or phone substring with `q`. Repeat `phone_number` to resolve up to 50 numbers to their contacts in one request, raising `limit` to at least the number of values you pass. Pass `include_total=true` to add the total number of matching contacts to the response.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "email", "value": "user@example.com", "description": "Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page." }, { "disabled": false, "key": "phone_number", "value": "+31612345678", "description": "Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set `limit` to at least the number of values you pass. The default `limit` is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so `phone_number=a&phone_number=b&email=c` asks for a contact whose phone number is `a` or `b` and whose email is `c`. Encode the leading plus sign as `%2B` (an unencoded `+` arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page." }, { "disabled": false, "key": "phone_number", "value": "+31698765432", "description": "Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set `limit` to at least the number of values you pass. The default `limit` is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so `phone_number=a&phone_number=b&email=c` asks for a contact whose phone number is `a` or `b` and whose email is `c`. Encode the leading plus sign as `%2B` (an unencoded `+` arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page." }, { "disabled": false, "key": "external_id", "value": "user_12345", "description": "Return the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page." }, { "disabled": false, "key": "q", "value": "acme.com", "description": "Case-insensitive substring match against the contact's email address, first name, last name, or phone number. Phone matching is over the digits of the international form, so a full pasted number, a formatted number, or trailing digits all match; a national form with a leading trunk zero does not." }, { "disabled": false, "key": "identifier", "value": "email", "description": "Filter to contacts that have a specific identifier on file." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "include_total", "value": "false", "description": "When true, the response includes a `total` field with the total number of items matching the request's filters across all pages." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contacts?email=user@example.com&phone_number=+31612345678&phone_number=+31698765432&external_id=user_12345&q=acme.com&identifier=email&limit=25&include_total=false" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "b7432df5-e28c-8a7e-8798-b5d4d4c22994", "name": "A page of contacts.", "originalRequest": { "name": "List contacts", "description": { "content": "Returns a paginated list of contacts in the workspace, newest first. Look up a single contact by its exact `email`, `phone_number`, or `external_id`, or search by email, first name, last name, or phone substring with `q`. Repeat `phone_number` to resolve up to 50 numbers to their contacts in one request, raising `limit` to at least the number of values you pass. Pass `include_total=true` to add the total number of matching contacts to the response.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "email", "value": "user@example.com", "description": "Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page." }, { "disabled": false, "key": "phone_number", "value": "+31612345678", "description": "Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set `limit` to at least the number of values you pass. The default `limit` is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so `phone_number=a&phone_number=b&email=c` asks for a contact whose phone number is `a` or `b` and whose email is `c`. Encode the leading plus sign as `%2B` (an unencoded `+` arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page." }, { "disabled": false, "key": "phone_number", "value": "+31698765432", "description": "Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set `limit` to at least the number of values you pass. The default `limit` is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so `phone_number=a&phone_number=b&email=c` asks for a contact whose phone number is `a` or `b` and whose email is `c`. Encode the leading plus sign as `%2B` (an unencoded `+` arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page." }, { "disabled": false, "key": "external_id", "value": "user_12345", "description": "Return the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page." }, { "disabled": false, "key": "q", "value": "acme.com", "description": "Case-insensitive substring match against the contact's email address, first name, last name, or phone number. Phone matching is over the digits of the international form, so a full pasted number, a formatted number, or trailing digits all match; a national form with a leading trunk zero does not." }, { "disabled": false, "key": "identifier", "value": "email", "description": "Filter to contacts that have a specific identifier on file." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "include_total", "value": "false", "description": "When true, the response includes a `total` field with the total number of items matching the request's filters across all pages." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contacts?email=user@example.com&phone_number=+31612345678&phone_number=+31698765432&external_id=user_12345&q=acme.com&identifier=email&limit=25&include_total=false" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"con_01krdgeqcxet5s7t44vh8rt9mg\",\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"audiences\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\"\n }\n ],\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "ddc1a1ca-8266-806a-8066-9b1677fe0dbc", "name": "Create or update contacts in bulk", "request": { "name": "Create or update contacts in bulk", "description": { "content": "Creates or updates up to 1,000 contacts in one request. Each entry is matched automatically against every identifier it supplies: its email address (trimmed and lowercased), its phone number (normalized to international form), and your own `external_id`. An entry with no match creates a contact. An entry whose identifiers all match one contact updates the supplied fields and preserves omitted fields. This lets an email address change under a stable `external_id` without creating a second contact. An entry whose identifiers belong to several contacts fails with an error naming each match; contacts are never merged automatically. Supplying `match_on` makes that field the only matching key, and every entry must include it. You can also add every contact in the request to up to 10 audiences.\n\nEach entry succeeds or fails on its own: the response lists one result per contact in submission order (`created`, `updated`, or `failed` with the reason), and a failed entry does not abort the rest. If the request itself is invalid, for example when an entry in `audience_ids` does not exist, the whole request fails with a validation error and no contacts are written.\n\nThe JSON request body can contain up to 24 MiB (25,165,824 bytes), including escaped characters. Larger requests return HTTP `413` before any contacts are written. Split an oversized request into smaller batches.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", "batch" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contacts/batch" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"contacts\": [\n {\n \"email\": \"alice@acme.com\",\n \"first_name\": \"Alice\",\n \"last_name\": \"Anderson\"\n },\n {\n \"email\": \"bob@acme.com\",\n \"first_name\": \"Bob\",\n \"last_name\": \"Baker\"\n }\n ],\n \"audience_ids\": [\n \"adn_01krdgeqcxet5s7t44vh8rt9mg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "1f4e3a58-223a-8095-859f-be72b4586938", "name": "Per-contact results, in submission order.", "originalRequest": { "name": "Create or update contacts in bulk", "description": { "content": "Creates or updates up to 1,000 contacts in one request. Each entry is matched automatically against every identifier it supplies: its email address (trimmed and lowercased), its phone number (normalized to international form), and your own `external_id`. An entry with no match creates a contact. An entry whose identifiers all match one contact updates the supplied fields and preserves omitted fields. This lets an email address change under a stable `external_id` without creating a second contact. An entry whose identifiers belong to several contacts fails with an error naming each match; contacts are never merged automatically. Supplying `match_on` makes that field the only matching key, and every entry must include it. You can also add every contact in the request to up to 10 audiences.\n\nEach entry succeeds or fails on its own: the response lists one result per contact in submission order (`created`, `updated`, or `failed` with the reason), and a failed entry does not abort the rest. If the request itself is invalid, for example when an entry in `audience_ids` does not exist, the whole request fails with a validation error and no contacts are written.\n\nThe JSON request body can contain up to 24 MiB (25,165,824 bytes), including escaped characters. Larger requests return HTTP `413` before any contacts are written. Split an oversized request into smaller batches.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", "batch" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contacts/batch" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"contacts\": [\n {\n \"email\": \"alice@acme.com\",\n \"first_name\": \"Alice\",\n \"last_name\": \"Anderson\"\n },\n {\n \"email\": \"bob@acme.com\",\n \"first_name\": \"Bob\",\n \"last_name\": \"Baker\"\n }\n ],\n \"audience_ids\": [\n \"adn_01krdgeqcxet5s7t44vh8rt9mg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"entry\": {\n \"email\": \"alice@acme.com\",\n \"phone_number\": null,\n \"external_id\": null\n },\n \"matched_on\": \"email\",\n \"status\": \"created\",\n \"contact_id\": \"con_01krdgeqcxet5s7t44vh8rt9mg\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d9eacda2-d20e-8644-8a5e-0b256cae7533", "name": "Get a contact", "request": { "name": "Get a contact", "description": { "content": "Returns a single contact, including its custom `data` values and the channels it can be reached on. To find a contact's ID by email address or `external_id`, use [List contacts](https://bird.com/docs/api/reference/list-contacts).\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to fetch." } ], "raw": "{{BIRD_API_URL}}/v1/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "6159e00b-b4ee-8ab7-86e1-9e6832db1559", "name": "The contact.", "originalRequest": { "name": "Get a contact", "description": { "content": "Returns a single contact, including its custom `data` values and the channels it can be reached on. To find a contact's ID by email address or `external_id`, use [List contacts](https://bird.com/docs/api/reference/list-contacts).\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to fetch." } ], "raw": "{{BIRD_API_URL}}/v1/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"con_01krdgeqcxet5s7t44vh8rt9mg\",\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"audiences\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\"\n }\n ],\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "1d211b4f-0bc4-811b-8ebc-990875cb4766", "name": "Update a contact", "request": { "name": "Update a contact", "description": { "content": "Updates a contact. Supplied fields are changed and omitted fields are left unchanged; set `first_name`, `last_name`, or `external_id` to `null` to clear them. Custom values in `data` are merged: keys you supply are set, keys set to `null` are removed, and keys you omit are unchanged.\n\nChanging the email address, phone number, or `external_id` to a value already used by another contact returns a conflict error. A contact always keeps at least one identifier. Clearing both email and phone in the same contact is rejected.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to update." } ], "raw": "{{BIRD_API_URL}}/v1/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"first_name\": \"Alice\",\n \"last_name\": \"Anderson\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "8abdaade-ffcf-8503-8fd3-3fccb0f8e71a", "name": "The updated contact.", "originalRequest": { "name": "Update a contact", "description": { "content": "Updates a contact. Supplied fields are changed and omitted fields are left unchanged; set `first_name`, `last_name`, or `external_id` to `null` to clear them. Custom values in `data` are merged: keys you supply are set, keys set to `null` are removed, and keys you omit are unchanged.\n\nChanging the email address, phone number, or `external_id` to a value already used by another contact returns a conflict error. A contact always keeps at least one identifier. Clearing both email and phone in the same contact is rejected.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to update." } ], "raw": "{{BIRD_API_URL}}/v1/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"first_name\": \"Alice\",\n \"last_name\": \"Anderson\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"con_01krdgeqcxet5s7t44vh8rt9mg\",\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"audiences\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\"\n }\n ],\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "a8a7910b-0df6-8c2b-82a6-fae8eb7fedc7", "name": "Delete a contact", "request": { "name": "Delete a contact", "description": { "content": "Deletes a contact permanently and removes it from every audience it belongs to. Suppression records for the address are not affected: an unsubscribed or bounced address stays suppressed even after the contact is deleted. Deletion is refused while any eSIM subscriber links to the contact, including subscribers without an active eSIM. Subscriber links cannot currently be deleted, detached, or anonymized; ending or releasing an eSIM does not restore Contact deletion.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to delete." } ], "raw": "{{BIRD_API_URL}}/v1/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "response": [ { "id": "d807e772-dcd5-8a4d-8f87-0989c52caf74", "name": "Contact deleted.", "originalRequest": { "name": "Delete a contact", "description": { "content": "Deletes a contact permanently and removes it from every audience it belongs to. Suppression records for the address are not affected: an unsubscribed or bounced address stays suppressed even after the contact is deleted. Deletion is refused while any eSIM subscriber links to the contact, including subscribers without an active eSIM. Subscriber links cannot currently be deleted, detached, or anonymized; ending or releasing an eSIM does not restore Contact deletion.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to delete." } ], "raw": "{{BIRD_API_URL}}/v1/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "status": "No Content", "code": 204, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "46108391-1ae2-87ae-8b09-57c860223623", "name": "Create a contact property", "request": { "name": "Create a contact property", "description": { "content": "Defines a custom property that contacts in the workspace can carry. The key becomes available in contact `data` and as a template variable in broadcasts. The key and type cannot be changed after creation.\n\nA key already in use returns a conflict error. A workspace can hold at most 200 properties; archived properties keep their key and count toward that limit.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contact-properties" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"key\": \"plan\",\n \"type\": \"string\",\n \"fallback_value\": \"free\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "1b1550e2-b57a-8889-8d74-2acaa0a857b1", "name": "Contact property created.", "originalRequest": { "name": "Create a contact property", "description": { "content": "Defines a custom property that contacts in the workspace can carry. The key becomes available in contact `data` and as a template variable in broadcasts. The key and type cannot be changed after creation.\n\nA key already in use returns a conflict error. A workspace can hold at most 200 properties; archived properties keep their key and count toward that limit.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contact-properties" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"key\": \"plan\",\n \"type\": \"string\",\n \"fallback_value\": \"free\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"prp_01krdgeqcxet5s7t44vh8rt9mg\",\n \"key\": \"plan\",\n \"type\": \"string\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "5c593a8f-e246-81c4-8dc0-d827f06e256c", "name": "List contact properties", "request": { "name": "List contact properties", "description": { "content": "Returns a paginated list of the workspace's contact properties, newest first. Archived properties are included; check each entry's `archived` flag.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contact-properties?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "62d42aea-1940-8b89-85fd-954f6355e4d4", "name": "A page of contact properties.", "originalRequest": { "name": "List contact properties", "description": { "content": "Returns a paginated list of the workspace's contact properties, newest first. Archived properties are included; check each entry's `archived` flag.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/contact-properties?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"prp_01krdgeqcxet5s7t44vh8rt9mg\",\n \"key\": \"plan\",\n \"type\": \"string\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "e6915f99-3d13-847a-893f-241cd1966f48", "name": "Get a contact property", "request": { "name": "Get a contact property", "description": { "content": "Returns a single contact property: its immutable key and type, the fallback value, and whether it is archived.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to fetch." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "5d05479b-25b7-8092-8a49-c7c0f281df5a", "name": "The contact property.", "originalRequest": { "name": "Get a contact property", "description": { "content": "Returns a single contact property: its immutable key and type, the fallback value, and whether it is archived.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to fetch." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"prp_01krdgeqcxet5s7t44vh8rt9mg\",\n \"key\": \"plan\",\n \"type\": \"string\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "ca7af2d4-cb22-8193-88cb-e607f979e37f", "name": "Update a contact property", "request": { "name": "Update a contact property", "description": { "content": "Updates a contact property's fallback value, the only mutable field. The key and type cannot be changed after creation; create a new property instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to update." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"fallback_value\": \"free\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "5a25e3eb-93f9-87cf-8891-5d777b01bec5", "name": "The updated contact property.", "originalRequest": { "name": "Update a contact property", "description": { "content": "Updates a contact property's fallback value, the only mutable field. The key and type cannot be changed after creation; create a new property instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to update." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"fallback_value\": \"free\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"prp_01krdgeqcxet5s7t44vh8rt9mg\",\n \"key\": \"plan\",\n \"type\": \"string\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "24249d93-5c11-8353-8caa-6e699f74ad1c", "name": "Archive a contact property", "request": { "name": "Archive a contact property", "description": { "content": "Archives a contact property. The key stops being accepted in contact writes, but every value already stored on your contacts is preserved and still returned when you read a contact.\n\nArchiving a live property succeeds whatever else reads the key. From then on the property behaves as though it does not exist for new work: it is gone from the property pickers, and publishing a template version whose content reads `bird.contact.` is refused, naming the property. Template versions published before you archived it are untouched and keep sending, filling the key from the values your contacts already carry.\n\nThe key stays reserved and still counts toward the workspace's 200-property limit, so it cannot be re-created with a different type. Archiving an already-archived property returns a conflict error; reverse it with [Unarchive a contact property](https://bird.com/docs/api/reference/unarchive-contact-property).\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id", "archive" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to archive." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id/archive" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "response": [ { "id": "1523060d-660f-88bc-8fcb-9933ba0c5ab0", "name": "The archived contact property.", "originalRequest": { "name": "Archive a contact property", "description": { "content": "Archives a contact property. The key stops being accepted in contact writes, but every value already stored on your contacts is preserved and still returned when you read a contact.\n\nArchiving a live property succeeds whatever else reads the key. From then on the property behaves as though it does not exist for new work: it is gone from the property pickers, and publishing a template version whose content reads `bird.contact.` is refused, naming the property. Template versions published before you archived it are untouched and keep sending, filling the key from the values your contacts already carry.\n\nThe key stays reserved and still counts toward the workspace's 200-property limit, so it cannot be re-created with a different type. Archiving an already-archived property returns a conflict error; reverse it with [Unarchive a contact property](https://bird.com/docs/api/reference/unarchive-contact-property).\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id", "archive" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to archive." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id/archive" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"prp_01krdgeqcxet5s7t44vh8rt9mg\",\n \"key\": \"plan\",\n \"type\": \"string\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "2c8f0ff1-607b-85ba-8f57-2687e3e4a34f", "name": "Unarchive a contact property", "request": { "name": "Unarchive a contact property", "description": { "content": "Reactivates an archived contact property. The key is accepted in contact writes and new template versions. Stored values are unchanged. Unarchiving a property that is not archived returns a conflict error.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id", "unarchive" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to unarchive." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id/unarchive" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "response": [ { "id": "ea6e6eaa-4ba2-8857-8c12-dd6dbe8fad75", "name": "The reactivated contact property.", "originalRequest": { "name": "Unarchive a contact property", "description": { "content": "Reactivates an archived contact property. The key is accepted in contact writes and new template versions. Stored values are unchanged. Unarchiving a property that is not archived returns a conflict error.\n", "type": "text/plain" }, "url": { "path": [ "v1", "contact-properties", ":property_id", "unarchive" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "property_id", "description": "(Required) ID of the contact property to unarchive." } ], "raw": "{{BIRD_API_URL}}/v1/contact-properties/:property_id/unarchive" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"prp_01krdgeqcxet5s7t44vh8rt9mg\",\n \"key\": \"plan\",\n \"type\": \"string\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "2d52d09b-d48c-84a4-8dfc-fe8cc92457c2", "name": "email-audiences", "description": { "content": "Audiences are the recipient lists broadcasts are sent to. An audience holds a set of contacts that you manage through the API. The contacts in the audience at send time become the broadcast's recipients after suppressions are applied. A contact can belong to multiple audiences.\n", "type": "text/plain" }, "item": [ { "id": "63cf1783-9cde-8493-8db4-b906641e4d2e", "name": "Create an audience", "request": { "name": "Create an audience", "description": { "content": "Creates an audience in the workspace. New audiences start empty: add members with [Add contacts to an audience](https://bird.com/docs/api/reference/assign-audience-contacts) or through [Create or update contacts in bulk](https://bird.com/docs/api/reference/create-contact-batch). The `type` field currently accepts only `static` audiences.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/audiences" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Newsletter subscribers\",\n \"description\": \"Contacts who opted into the monthly product newsletter\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "ebd5c836-3052-8f92-82d8-bc921e96ddcd", "name": "The created audience.", "originalRequest": { "name": "Create an audience", "description": { "content": "Creates an audience in the workspace. New audiences start empty: add members with [Add contacts to an audience](https://bird.com/docs/api/reference/assign-audience-contacts) or through [Create or update contacts in bulk](https://bird.com/docs/api/reference/create-contact-batch). The `type` field currently accepts only `static` audiences.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/audiences" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"name\": \"Newsletter subscribers\",\n \"description\": \"Contacts who opted into the monthly product newsletter\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\",\n \"type\": \"static\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "6af6c53c-1afa-8f6e-8808-2190500d081a", "name": "List audiences", "request": { "name": "List audiences", "description": { "content": "Returns a paginated list of audiences in the workspace, newest first. Filter to audiences whose name contains a substring with `q`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "q", "value": "newsletter", "description": "Case-insensitive substring match against the audience's name." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/audiences?q=newsletter&limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "7602dad0-3e82-8bcb-8abd-7910b4e58224", "name": "A page of audiences.", "originalRequest": { "name": "List audiences", "description": { "content": "Returns a paginated list of audiences in the workspace, newest first. Filter to audiences whose name contains a substring with `q`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "q", "value": "newsletter", "description": "Case-insensitive substring match against the audience's name." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/audiences?q=newsletter&limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\",\n \"type\": \"static\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "1559e704-a597-8a06-84c9-9436d78f13a1", "name": "Get an audience", "request": { "name": "Get an audience", "description": { "content": "Returns a single audience: its name, description, and type. The member list is separate; fetch it with [List an audience's contacts](https://bird.com/docs/api/reference/list-audience-contacts).\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to fetch." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "163b1f25-3196-8fff-83e8-18e5b3f450c0", "name": "The audience.", "originalRequest": { "name": "Get an audience", "description": { "content": "Returns a single audience: its name, description, and type. The member list is separate; fetch it with [List an audience's contacts](https://bird.com/docs/api/reference/list-audience-contacts).\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to fetch." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\",\n \"type\": \"static\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "501124df-3001-8d4d-839d-0cd9b72d6591", "name": "Update an audience", "request": { "name": "Update an audience", "description": { "content": "Updates an audience's name or description. Omitted fields are left unchanged; set `description` to `null` to clear it.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to update." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"name\": \"Newsletter subscribers\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "f54f355b-3c10-82f4-8a9d-7e834e39dc28", "name": "The updated audience.", "originalRequest": { "name": "Update an audience", "description": { "content": "Updates an audience's name or description. Omitted fields are left unchanged; set `description` to `null` to clear it.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to update." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"name\": \"Newsletter subscribers\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\",\n \"type\": \"static\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "2cbb18fe-44cf-8639-8d04-73eb73f2d503", "name": "Delete an audience", "request": { "name": "Delete an audience", "description": { "content": "Deletes an audience and its memberships. Contacts themselves are not deleted. An audience cannot be deleted while a broadcast targeting it is scheduled, accepted, sending, or canceling; cancel that broadcast first, then retry.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to delete." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "response": [ { "id": "c0d63db4-db26-8c56-88e0-4820867f3983", "name": "The audience was deleted.", "originalRequest": { "name": "Delete an audience", "description": { "content": "Deletes an audience and its memberships. Contacts themselves are not deleted. An audience cannot be deleted while a broadcast targeting it is scheduled, accepted, sending, or canceling; cancel that broadcast first, then retry.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to delete." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "status": "No Content", "code": 204, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "a4c4ae74-79b6-8184-81c8-bad98b0fcdc2", "name": "List an audience's contacts", "request": { "name": "List an audience's contacts", "description": { "content": "Lists the contacts in a static audience as a cursor page, ordered by the time each contact joined the audience, most recent first. Each entry is the contact together with the time it joined.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "q", "value": "acme.com", "description": "Case-insensitive substring match against a contact's email address or the digits in its international phone number." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience whose contacts to list." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts?q=acme.com&limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "5cb414ad-6b62-898c-8ab4-98f721cca12f", "name": "A page of the audience's contacts.", "originalRequest": { "name": "List an audience's contacts", "description": { "content": "Lists the contacts in a static audience as a cursor page, ordered by the time each contact joined the audience, most recent first. Each entry is the contact together with the time it joined.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "q", "value": "acme.com", "description": "Case-insensitive substring match against a contact's email address or the digits in its international phone number." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience whose contacts to list." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts?q=acme.com&limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"contact\": {\n \"id\": \"con_01krdgeqcxet5s7t44vh8rt9mg\",\n \"email\": \"alice@acme.com\",\n \"phone_number\": \"+31612345678\",\n \"audiences\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\"\n }\n ],\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n },\n \"joined_at\": \"2026-05-21T10:30:00Z\",\n \"audiences\": [\n {\n \"id\": \"adn_01krdgeqcxet5s7t44vh8rt9mg\",\n \"name\": \"Newsletter subscribers\"\n }\n ]\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3239bdda-4528-8bb2-8b6a-151b3b52f7ba", "name": "Assign contacts to an audience", "request": { "name": "Assign contacts to an audience", "description": { "content": "Adds up to 1,000 contacts to an audience. Adding is idempotent: contacts that are already members are left in place and keep their original join time. If any contact ID does not exist in the workspace, the whole request fails with `422 Unprocessable Entity` and no contacts are added.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to add contacts to." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"contact_ids\": [\n \"con_01krdgeqcxet5s7t44vh8rt9mg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "15e3e11d-35fa-8e23-86a7-2a8226785acd", "name": "Contacts added to the audience.", "originalRequest": { "name": "Assign contacts to an audience", "description": { "content": "Adds up to 1,000 contacts to an audience. Adding is idempotent: contacts that are already members are left in place and keep their original join time. If any contact ID does not exist in the workspace, the whole request fails with `422 Unprocessable Entity` and no contacts are added.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to add contacts to." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"contact_ids\": [\n \"con_01krdgeqcxet5s7t44vh8rt9mg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "No Content", "code": 204, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "df94e2f8-35d3-8be9-8c00-24ef205fe8af", "name": "Unassign contacts from an audience", "request": { "name": "Unassign contacts from an audience", "description": { "content": "Removes up to 1,000 contacts from an audience. Contacts that are not members are skipped. If any contact ID does not exist in the workspace, the whole request fails with `422 Unprocessable Entity` and no memberships are removed. The contacts themselves are not deleted and remain members of any other audiences.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts", "remove" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to remove contacts from." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts/remove" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"contact_ids\": [\n \"con_01krdgeqcxet5s7t44vh8rt9mg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "038476fd-3e67-80ee-8420-30789ead5bb5", "name": "Contacts removed from the audience.", "originalRequest": { "name": "Unassign contacts from an audience", "description": { "content": "Removes up to 1,000 contacts from an audience. Contacts that are not members are skipped. If any contact ID does not exist in the workspace, the whole request fails with `422 Unprocessable Entity` and no memberships are removed. The contacts themselves are not deleted and remain members of any other audiences.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts", "remove" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to remove contacts from." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts/remove" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"contact_ids\": [\n \"con_01krdgeqcxet5s7t44vh8rt9mg\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "No Content", "code": 204, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d1331ca4-682e-85c9-8aa5-7d0e1ee41776", "name": "Unassign a contact from an audience", "request": { "name": "Unassign a contact from an audience", "description": { "content": "Removes a contact's membership in an audience. The contact itself is not deleted and remains a member of any other audiences. Removing a contact that is not a member of the audience succeeds with no effect (`204 No Content`); an unknown audience or contact returns a not-found error.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to remove the contact from." }, { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to remove." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "response": [ { "id": "a1afd17f-f963-847b-89a2-d5bc2ecd1a06", "name": "The contact was removed from the audience, or was already not a member.", "originalRequest": { "name": "Unassign a contact from an audience", "description": { "content": "Removes a contact's membership in an audience. The contact itself is not deleted and remains a member of any other audiences. Removing a contact that is not a member of the audience succeeds with no effect (`204 No Content`); an unknown audience or contact returns a not-found error.\n", "type": "text/plain" }, "url": { "path": [ "v1", "audiences", ":audience_id", "contacts", ":contact_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "audience_id", "description": "(Required) ID of the audience to remove the contact from." }, { "disabled": false, "type": "any", "value": "", "key": "contact_id", "description": "(Required) ID of the contact to remove." } ], "raw": "{{BIRD_API_URL}}/v1/audiences/:audience_id/contacts/:contact_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "status": "No Content", "code": 204, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "6c536cc2-35dc-8173-8c6e-a55ec6b5f7a7", "name": "sms-messages", "description": { "content": "Send SMS messages to recipients you address by phone number, and read their delivery status and lifecycle events. Each message is one recipient and one body; set `category` to control opt-out policy and per-country compliance.\n", "type": "text/plain" }, "item": [ { "id": "a6f55351-1cf3-89e9-8fc9-0fbeed0c84d4", "name": "Create an SMS message", "request": { "name": "Create an SMS message", "description": { "content": "Sends one SMS to one recipient with exactly one content form: `text`, which\nrequires `category` and `from`, or a stored `template`, which supplies its\ncategory. A workspace template requires `from`, while a built-in template\nselects its sender. To submit up to 100 independent messages in one request, use\n[Send a batch of SMS messages](https://bird.com/docs/api/reference/create-sms-message-batch)\ninstead.\n\nThe `202 Accepted` response means the API durably accepted the message for\nasynchronous delivery. Delivery remains pending; follow it with\n[Get an SMS message](https://bird.com/docs/api/reference/get-sms-message) or by subscribing\nto `sms.*` webhook events.\n\nAn invalid field, more than 12 segments, a disabled destination country, or\na sender not permitted for the destination returns `422`. Insufficient\nwallet balance returns `402`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/sms/messages" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"+14155550100\",\n \"from\": \"+15557654321\",\n \"text\": \"Your verification code is 123456.\",\n \"category\": \"authentication\",\n \"options\": {\n \"smart_encoding\": true\n },\n \"tags\": [\n {\n \"name\": \"campaign\",\n \"value\": \"signup\"\n }\n ],\n \"metadata\": {\n \"user_id\": \"usr_12345\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "fee21876-e0fd-872f-8b5a-e324f1d0d43e", "name": "Message accepted for asynchronous delivery.", "originalRequest": { "name": "Create an SMS message", "description": { "content": "Sends one SMS to one recipient with exactly one content form: `text`, which\nrequires `category` and `from`, or a stored `template`, which supplies its\ncategory. A workspace template requires `from`, while a built-in template\nselects its sender. To submit up to 100 independent messages in one request, use\n[Send a batch of SMS messages](https://bird.com/docs/api/reference/create-sms-message-batch)\ninstead.\n\nThe `202 Accepted` response means the API durably accepted the message for\nasynchronous delivery. Delivery remains pending; follow it with\n[Get an SMS message](https://bird.com/docs/api/reference/get-sms-message) or by subscribing\nto `sms.*` webhook events.\n\nAn invalid field, more than 12 segments, a disabled destination country, or\na sender not permitted for the destination returns `422`. Insufficient\nwallet balance returns `402`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/sms/messages" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"+14155550100\",\n \"from\": \"+15557654321\",\n \"text\": \"Your verification code is 123456.\",\n \"category\": \"authentication\",\n \"options\": {\n \"smart_encoding\": true\n },\n \"tags\": [\n {\n \"name\": \"campaign\",\n \"value\": \"signup\"\n }\n ],\n \"metadata\": {\n \"user_id\": \"usr_12345\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"sms_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"status\": \"scheduled\",\n \"to\": \"+15551234567\",\n \"from\": \"+15557654321\",\n \"text\": \"Your order has shipped and is on its way.\",\n \"category\": \"transactional\",\n \"requested_language\": \"pt-BR\",\n \"resolved_language\": \"pt-BR\",\n \"template_id\": \"smt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_version_id\": \"smv_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_content_hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\",\n \"segments\": {\n \"count\": 1,\n \"encoding\": \"GSM_7BIT\",\n \"characters\": 41\n },\n \"cost\": {\n \"amount\": \"0.00990\",\n \"currency_code\": \"USD\",\n \"transaction_amount\": \"0.00790\",\n \"passthrough_amount\": \"0.00200\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"options\": {\n \"smart_encoding\": true\n },\n \"carrier\": \"Verizon\",\n \"mcc_mnc\": \"311480\",\n \"last_error\": {\n \"code\": \"invalid_destination\",\n \"description\": \"Carrier filtered as spam\"\n },\n \"created_at\": \"2026-05-21T12:00:00Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "e19f29ad-efee-8c51-8e49-6e44c87bee76", "name": "List SMS messages", "request": { "name": "List SMS messages", "description": { "content": "Returns the workspace's SMS messages as a cursor-paginated list, newest\nfirst. Filter by direction, status, category, recipient, sender, failure\nreason, tag, or creation time; pass the response's `next_cursor` back as\n`starting_after` to fetch the next page. To follow a single message's\ndelivery, use [Get an SMS message](https://bird.com/docs/api/reference/get-sms-message)\ninstead.\n\nMessages are retained for **30 days**. A `created_after` earlier than that\nis accepted and raised to the retention bound rather than rejected, so a\nwider window returns what is still retained instead of failing. Messages\nolder than the retention window cannot be retrieved.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "created_after", "value": "2026-05-01T00:00:00Z", "description": "Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": false, "key": "created_before", "value": "2026-06-01T00:00:00Z", "description": "Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": true, "key": "direction", "value": "", "description": "Filter by direction. Omit for both." }, { "disabled": true, "key": "status", "value": "", "description": "Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`. `scheduled` and `canceled` are accepted but match nothing until send-later scheduling ships.\n" }, { "disabled": true, "key": "status", "value": "", "description": "Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`. `scheduled` and `canceled` are accepted but match nothing until send-later scheduling ships.\n" }, { "disabled": true, "key": "error_code", "value": "", "description": "Keep only messages whose failure reason (`last_error.code`) matches; repeat the parameter to match any of several. One of `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_fraud_protection`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, or `unknown`.\n" }, { "disabled": true, "key": "error_code", "value": "", "description": "Keep only messages whose failure reason (`last_error.code`) matches; repeat the parameter to match any of several. One of `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_fraud_protection`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, or `unknown`.\n" }, { "disabled": true, "key": "category", "value": "", "description": "Filter by category." }, { "disabled": false, "key": "to", "value": "+14155550100", "description": "Filter by recipient phone number (E.164 exact match)." }, { "disabled": false, "key": "from", "value": "+15557654321", "description": "Filter by sender (E.164, alphanumeric, or short code; exact match)." }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/sms/messages?limit=25&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&to=+14155550100&from=+15557654321" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "7cc25a6c-5f36-89fc-8b3b-57c61db9ffa0", "name": "Paginated list of messages.", "originalRequest": { "name": "List SMS messages", "description": { "content": "Returns the workspace's SMS messages as a cursor-paginated list, newest\nfirst. Filter by direction, status, category, recipient, sender, failure\nreason, tag, or creation time; pass the response's `next_cursor` back as\n`starting_after` to fetch the next page. To follow a single message's\ndelivery, use [Get an SMS message](https://bird.com/docs/api/reference/get-sms-message)\ninstead.\n\nMessages are retained for **30 days**. A `created_after` earlier than that\nis accepted and raised to the retention bound rather than rejected, so a\nwider window returns what is still retained instead of failing. Messages\nolder than the retention window cannot be retrieved.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "created_after", "value": "2026-05-01T00:00:00Z", "description": "Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": false, "key": "created_before", "value": "2026-06-01T00:00:00Z", "description": "Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": true, "key": "direction", "value": "", "description": "Filter by direction. Omit for both." }, { "disabled": true, "key": "status", "value": "", "description": "Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`. `scheduled` and `canceled` are accepted but match nothing until send-later scheduling ships.\n" }, { "disabled": true, "key": "status", "value": "", "description": "Keep only messages whose current `status` matches; repeat the parameter to match any of several. One of `scheduled`, `accepted`, `sent`, `delivered`, `undelivered`, `failed`, `rejected`, `canceled`, `expired`, or `received`. `scheduled` and `canceled` are accepted but match nothing until send-later scheduling ships.\n" }, { "disabled": true, "key": "error_code", "value": "", "description": "Keep only messages whose failure reason (`last_error.code`) matches; repeat the parameter to match any of several. One of `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_fraud_protection`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, or `unknown`.\n" }, { "disabled": true, "key": "error_code", "value": "", "description": "Keep only messages whose failure reason (`last_error.code`) matches; repeat the parameter to match any of several. One of `invalid_destination`, `unreachable`, `blocked_by_carrier`, `blocked_by_fraud_protection`, `blocked_by_recipient`, `landline_unreachable`, `content_rejected`, `sender_unregistered`, `recipient_opted_out`, `provider_unavailable`, `insufficient_balance`, or `unknown`.\n" }, { "disabled": true, "key": "category", "value": "", "description": "Filter by category." }, { "disabled": false, "key": "to", "value": "+14155550100", "description": "Filter by recipient phone number (E.164 exact match)." }, { "disabled": false, "key": "from", "value": "+15557654321", "description": "Filter by sender (E.164, alphanumeric, or short code; exact match)." }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/sms/messages?limit=25&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&to=+14155550100&from=+15557654321" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"sms_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"status\": \"scheduled\",\n \"to\": \"+15551234567\",\n \"from\": \"+15557654321\",\n \"text\": \"Your order has shipped and is on its way.\",\n \"category\": \"transactional\",\n \"requested_language\": \"pt-BR\",\n \"resolved_language\": \"pt-BR\",\n \"template_id\": \"smt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_version_id\": \"smv_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_content_hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\",\n \"segments\": {\n \"count\": 1,\n \"encoding\": \"GSM_7BIT\",\n \"characters\": 41\n },\n \"cost\": {\n \"amount\": \"0.00990\",\n \"currency_code\": \"USD\",\n \"transaction_amount\": \"0.00790\",\n \"passthrough_amount\": \"0.00200\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"options\": {\n \"smart_encoding\": true\n },\n \"carrier\": \"Verizon\",\n \"mcc_mnc\": \"311480\",\n \"last_error\": {\n \"code\": \"invalid_destination\",\n \"description\": \"Carrier filtered as spam\"\n },\n \"created_at\": \"2026-05-21T12:00:00Z\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "bce09ac3-361b-8256-8320-06fc25c18994", "name": "Create a batch of SMS messages", "request": { "name": "Create a batch of SMS messages", "description": { "content": "Sends up to 100 independent SMS messages in one request. Each item is a\ncomplete send request with its own recipient, content, ID, status, and\ncost. For a single message, use\n[Send an SMS message](https://bird.com/docs/api/reference/create-sms-message) instead.\n\nAcceptance is all-or-nothing: every item is validated before any is queued,\nand one invalid item rejects the whole batch with a `422` (nothing is\nsent). A batch from a workspace with no wallet balance fails with a `402`.\nThe `202` response lists the accepted messages in submission order; each\ndelivers asynchronously and is tracked individually, like a single send.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "batches" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/sms/batches" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"messages\": [\n {\n \"to\": \"+15551111111\",\n \"from\": \"+15557654321\",\n \"text\": \"Hi Alice!\",\n \"category\": \"marketing\"\n },\n {\n \"to\": \"+15552222222\",\n \"from\": \"+15557654321\",\n \"text\": \"Hi Bob!\",\n \"category\": \"marketing\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "07028984-1dfe-83f4-8427-273872c7ced0", "name": "Batch accepted for asynchronous delivery.", "originalRequest": { "name": "Create a batch of SMS messages", "description": { "content": "Sends up to 100 independent SMS messages in one request. Each item is a\ncomplete send request with its own recipient, content, ID, status, and\ncost. For a single message, use\n[Send an SMS message](https://bird.com/docs/api/reference/create-sms-message) instead.\n\nAcceptance is all-or-nothing: every item is validated before any is queued,\nand one invalid item rejects the whole batch with a `422` (nothing is\nsent). A batch from a workspace with no wallet balance fails with a `402`.\nThe `202` response lists the accepted messages in submission order; each\ndelivers asynchronously and is tracked individually, like a single send.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "batches" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/sms/batches" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"messages\": [\n {\n \"to\": \"+15551111111\",\n \"from\": \"+15557654321\",\n \"text\": \"Hi Alice!\",\n \"category\": \"marketing\"\n },\n {\n \"to\": \"+15552222222\",\n \"from\": \"+15557654321\",\n \"text\": \"Hi Bob!\",\n \"category\": \"marketing\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"sms_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"status\": \"scheduled\",\n \"to\": \"+15551234567\",\n \"from\": \"+15557654321\",\n \"text\": \"Your order has shipped and is on its way.\",\n \"category\": \"transactional\",\n \"requested_language\": \"pt-BR\",\n \"resolved_language\": \"pt-BR\",\n \"template_id\": \"smt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_version_id\": \"smv_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_content_hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\",\n \"segments\": {\n \"count\": 1,\n \"encoding\": \"GSM_7BIT\",\n \"characters\": 41\n },\n \"cost\": {\n \"amount\": \"0.00990\",\n \"currency_code\": \"USD\",\n \"transaction_amount\": \"0.00790\",\n \"passthrough_amount\": \"0.00200\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"options\": {\n \"smart_encoding\": true\n },\n \"carrier\": \"Verizon\",\n \"mcc_mnc\": \"311480\",\n \"last_error\": {\n \"code\": \"invalid_destination\",\n \"description\": \"Carrier filtered as spam\"\n },\n \"created_at\": \"2026-05-21T12:00:00Z\"\n }\n ],\n \"summary\": {\n \"accepted_count\": 2\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "4387010c-e925-8067-8eaf-e06f2fce3920", "name": "Get an SMS message", "request": { "name": "Get an SMS message", "description": { "content": "Returns a single SMS message: its current delivery status, segment breakdown, cost, and failure detail when it failed. The `status` advances asynchronously as delivery progresses, and `cost` is null until the message has been priced, so poll this operation (or subscribe to `sms.*` webhook events) after a send to confirm delivery. To scan messages in bulk, use [List SMS messages](https://bird.com/docs/api/reference/list-sms-messages) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages", ":message_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message, as returned in the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/sms/messages/:message_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "d1a7c66f-8742-85a9-8eca-dde00c0c1fda", "name": "SMS message with its current delivery status.", "originalRequest": { "name": "Get an SMS message", "description": { "content": "Returns a single SMS message: its current delivery status, segment breakdown, cost, and failure detail when it failed. The `status` advances asynchronously as delivery progresses, and `cost` is null until the message has been priced, so poll this operation (or subscribe to `sms.*` webhook events) after a send to confirm delivery. To scan messages in bulk, use [List SMS messages](https://bird.com/docs/api/reference/list-sms-messages) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages", ":message_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message, as returned in the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/sms/messages/:message_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"sms_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"status\": \"scheduled\",\n \"to\": \"+15551234567\",\n \"from\": \"+15557654321\",\n \"text\": \"Your order has shipped and is on its way.\",\n \"category\": \"transactional\",\n \"requested_language\": \"pt-BR\",\n \"resolved_language\": \"pt-BR\",\n \"template_id\": \"smt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_version_id\": \"smv_01krdgeqcxet5s7t44vh8rt9mg\",\n \"template_content_hash\": \"sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08\",\n \"segments\": {\n \"count\": 1,\n \"encoding\": \"GSM_7BIT\",\n \"characters\": 41\n },\n \"cost\": {\n \"amount\": \"0.00990\",\n \"currency_code\": \"USD\",\n \"transaction_amount\": \"0.00790\",\n \"passthrough_amount\": \"0.00200\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"options\": {\n \"smart_encoding\": true\n },\n \"carrier\": \"Verizon\",\n \"mcc_mnc\": \"311480\",\n \"last_error\": {\n \"code\": \"invalid_destination\",\n \"description\": \"Carrier filtered as spam\"\n },\n \"created_at\": \"2026-05-21T12:00:00Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "7e097f92-25b1-8380-8bf1-f80f71aa3e60", "name": "List events for an SMS message", "request": { "name": "List events for an SMS message", "description": { "content": "Returns the lifecycle event timeline for a message, in chronological order.", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages", ":message_id", "events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "type", "value": "", "description": "Filter by event type, such as `sms.delivered` or `sms.failed`." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the SMS message (`sms_` prefix), as returned when the message was accepted." } ], "raw": "{{BIRD_API_URL}}/v1/sms/messages/:message_id/events" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "2f55045e-01ac-8187-8d32-b12e54310704", "name": "Event timeline for this message.", "originalRequest": { "name": "List events for an SMS message", "description": { "content": "Returns the lifecycle event timeline for a message, in chronological order.", "type": "text/plain" }, "url": { "path": [ "v1", "sms", "messages", ":message_id", "events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "type", "value": "", "description": "Filter by event type, such as `sms.delivered` or `sms.failed`." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the SMS message (`sms_` prefix), as returned when the message was accepted." } ], "raw": "{{BIRD_API_URL}}/v1/sms/messages/:message_id/events" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"evt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"type\": \"sms.delivered\",\n \"occurred_at\": \"2026-05-21T12:00:04Z\",\n \"carrier\": \"Verizon\",\n \"mcc_mnc\": \"311480\",\n \"error\": {\n \"code\": \"invalid_destination\",\n \"description\": \"Carrier filtered as spam\"\n }\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "1c274daa-4808-8e92-8697-93bc2b8ad28a", "name": "verify-verifications", "description": { "content": "Send a one-time passcode to a recipient and check the code they enter. Create a verification to send a passcode over email or SMS, then submit the recipient's code to verify it.\n", "type": "text/plain" }, "item": [ { "id": "6279575e-eba9-8432-8ce5-ca0bbf6e6f3d", "name": "Create a verification", "request": { "name": "Create a verification", "description": { "content": "Creates a verification and sends the recipient a one-time passcode. Provide an email address, a phone number, or both in `to`. The service sends over one channel at a time and moves to the next planned channel if delivery fails.\n\nCalling this again for the same recipient reuses the verification in progress. During the resend cooldown, it returns the current state without sending, so nothing is charged and no send budget is spent. After the cooldown, it sends a fresh passcode, and that send draws on the recipient's hourly send cap exactly as a new verification does, so repeated resends can exhaust the cap and return `429` for the rest of that rolling hour. [Abuse guardrails](https://bird.com/docs/guides/verify/sending-verifications#abuse-guardrails) gives the figures.\n\nThe `200` response contains the current state, never the passcode. Submit the recipient's passcode with [Check a verification](https://bird.com/docs/api/reference/create-verification-check) before `expires_at`. An invalid recipient returns `422`; exceeding the send rate limit returns `429`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "verify", "verifications" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/verify/verifications" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": {\n \"phone_number\": \"+15551234567\"\n },\n \"metadata\": {\n \"correlation_id\": \"signup-7f3a\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "83f7032e-1285-8b2b-84ac-14bf8a00dcce", "name": "The verification's current state, whether newly opened or reused.", "originalRequest": { "name": "Create a verification", "description": { "content": "Creates a verification and sends the recipient a one-time passcode. Provide an email address, a phone number, or both in `to`. The service sends over one channel at a time and moves to the next planned channel if delivery fails.\n\nCalling this again for the same recipient reuses the verification in progress. During the resend cooldown, it returns the current state without sending, so nothing is charged and no send budget is spent. After the cooldown, it sends a fresh passcode, and that send draws on the recipient's hourly send cap exactly as a new verification does, so repeated resends can exhaust the cap and return `429` for the rest of that rolling hour. [Abuse guardrails](https://bird.com/docs/guides/verify/sending-verifications#abuse-guardrails) gives the figures.\n\nThe `200` response contains the current state, never the passcode. Submit the recipient's passcode with [Check a verification](https://bird.com/docs/api/reference/create-verification-check) before `expires_at`. An invalid recipient returns `422`; exceeding the send rate limit returns `429`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "verify", "verifications" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/verify/verifications" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": {\n \"phone_number\": \"+15551234567\"\n },\n \"metadata\": {\n \"correlation_id\": \"signup-7f3a\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"vrf_01krdgeqcxet5s7t44vh8rt9mg\",\n \"status\": \"pending\",\n \"reason\": null,\n \"to\": {\n \"email\": \"user@example.com\"\n },\n \"channels\": [\n {\n \"channel\": \"email\"\n }\n ],\n \"last_channel\": \"email\",\n \"expires_at\": \"2026-05-20T09:24:52Z\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-20T09:14:52Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "30267b99-fdb3-8c23-8b93-5e0f91d31c75", "name": "Create a verification passcode check", "request": { "name": "Create a verification passcode check", "description": { "content": "Checks a passcode for a recipient and returns the outcome together with the verification's current state. Identify the verification by the same `to` used to create it; you do not need to store a verification ID.\n\nA wrong or expired passcode returns `200 OK` with `success: false` and a `reason` such as `incorrect_code` or `expired`. `success: true` means the verification is complete. Each verification reports its final outcome once and cannot be checked again.\n\nAn error status is returned only when the check cannot be evaluated. A `404\nE13000` means no active verification matched the recipient: either none\nexists for it, or the most recent one is already resolved as verified,\nexpired, or out of attempts. One code covers all of those, so a `404` is not\nevidence the recipient failed to verify. Treat your own record of an earlier\n`success: true` as the outcome, and create a new verification only if the\nrecipient still needs to verify. A `422` indicates an invalid recipient. A\n`429` means passcodes for a recipient are being checked too quickly.\n", "type": "text/plain" }, "url": { "path": [ "v1", "verify", "verifications", "check" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/verify/verifications/check" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": {\n \"phone_number\": \"+15551234567\"\n },\n \"code\": \"123456\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "e7d09207-9cd9-8dfd-81b9-8fc67f174e01", "name": "The check outcome and the verification's current state.", "originalRequest": { "name": "Create a verification passcode check", "description": { "content": "Checks a passcode for a recipient and returns the outcome together with the verification's current state. Identify the verification by the same `to` used to create it; you do not need to store a verification ID.\n\nA wrong or expired passcode returns `200 OK` with `success: false` and a `reason` such as `incorrect_code` or `expired`. `success: true` means the verification is complete. Each verification reports its final outcome once and cannot be checked again.\n\nAn error status is returned only when the check cannot be evaluated. A `404\nE13000` means no active verification matched the recipient: either none\nexists for it, or the most recent one is already resolved as verified,\nexpired, or out of attempts. One code covers all of those, so a `404` is not\nevidence the recipient failed to verify. Treat your own record of an earlier\n`success: true` as the outcome, and create a new verification only if the\nrecipient still needs to verify. A `422` indicates an invalid recipient. A\n`429` means passcodes for a recipient are being checked too quickly.\n", "type": "text/plain" }, "url": { "path": [ "v1", "verify", "verifications", "check" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/verify/verifications/check" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": {\n \"phone_number\": \"+15551234567\"\n },\n \"code\": \"123456\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"success\": false,\n \"reason\": \"incorrect_code\",\n \"verification\": {\n \"id\": \"vrf_01krdgeqcxet5s7t44vh8rt9mg\",\n \"status\": \"pending\",\n \"reason\": null,\n \"to\": {\n \"email\": \"user@example.com\"\n },\n \"channels\": [\n {\n \"channel\": \"email\"\n }\n ],\n \"last_channel\": \"email\",\n \"expires_at\": \"2026-05-20T09:24:52Z\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-20T09:14:52Z\"\n },\n \"attempts_remaining\": 2\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "77160caa-8a3e-8484-8993-63f0d4b95876", "name": "Create the next verification channel attempt", "request": { "name": "Create the next verification channel attempt", "description": { "content": "Advances an in-progress verification to the next channel in its plan and sends a fresh passcode there. Identify the verification by the same `to` recipient used to create it; no verification ID is required.\n\nThe send bypasses the resend cooldown and does not draw on the recipient's hourly send cap; what bounds it is the channel plan, since each call advances by at most one channel. Passcodes sent earlier remain valid. The response sets `last_channel` to the most recent completed send. Concurrent requests each advance the plan by at most one channel and return committed state.\n\nA recipient with no in-progress verification returns `404 E13000`, whether none was ever created or the most recent one is already resolved. A recipient who has already verified is in that set, so a `404` here is not evidence they still need verifying, and creating another verification would send a passcode they no longer need. A plan with no further channel returns `422 NoNextChannel`; create the verification again to resend on the current channel. If every remaining channel fails, the operation returns `422 NoAvailableChannel`. Requests that exceed the send rate limit return `429`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "verify", "verifications", "next-channel" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/verify/verifications/next-channel" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": {\n \"phone_number\": \"+15551234567\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "2652c3c7-252f-8a1c-840d-81203de817f3", "name": "Verification state after the advance. `last_channel` identifies the most recent completed send.", "originalRequest": { "name": "Create the next verification channel attempt", "description": { "content": "Advances an in-progress verification to the next channel in its plan and sends a fresh passcode there. Identify the verification by the same `to` recipient used to create it; no verification ID is required.\n\nThe send bypasses the resend cooldown and does not draw on the recipient's hourly send cap; what bounds it is the channel plan, since each call advances by at most one channel. Passcodes sent earlier remain valid. The response sets `last_channel` to the most recent completed send. Concurrent requests each advance the plan by at most one channel and return committed state.\n\nA recipient with no in-progress verification returns `404 E13000`, whether none was ever created or the most recent one is already resolved. A recipient who has already verified is in that set, so a `404` here is not evidence they still need verifying, and creating another verification would send a passcode they no longer need. A plan with no further channel returns `422 NoNextChannel`; create the verification again to resend on the current channel. If every remaining channel fails, the operation returns `422 NoAvailableChannel`. Requests that exceed the send rate limit return `429`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "verify", "verifications", "next-channel" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/verify/verifications/next-channel" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": {\n \"phone_number\": \"+15551234567\"\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"vrf_01krdgeqcxet5s7t44vh8rt9mg\",\n \"status\": \"pending\",\n \"reason\": null,\n \"to\": {\n \"email\": \"user@example.com\"\n },\n \"channels\": [\n {\n \"channel\": \"email\"\n }\n ],\n \"last_channel\": \"email\",\n \"expires_at\": \"2026-05-20T09:24:52Z\",\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-20T09:14:52Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "3a8d3470-41eb-8f87-8cec-aa11702739ff", "name": "whatsapp-messages", "description": { "content": "Send WhatsApp messages, whether a template, free-form content, or interactive content the recipient can tap, and read the messages your workspace sent and received, including their current delivery status and lifecycle events.\n", "type": "text/plain" }, "item": [ { "id": "63f423fd-5126-8b29-8e47-cd5f90176593", "name": "List WhatsApp messages", "request": { "name": "List WhatsApp messages", "description": { "content": "Returns the workspace's WhatsApp messages as a cursor-paginated list,\nnewest first, outbound and inbound alike. Each message carries the one\ncontent object it was built from: `template`, or free-form `text`,\n`image`, `video`, `audio`, `sticker`, `document`, `location`,\n`interactive` or `contact_cards`. An inbound message carries\n`interactive_reply` when the contact tapped a reply button or a list row,\non an interactive message or on a template's quick reply. An inbound\nmessage whose content WhatsApp models and we do not carries `unsupported`\ninstead, naming the type rather than reading back empty.\nFilter by direction, status, recipient (`to`), sender (`from`),\nbusiness-scoped user ID (`bsuid`), group (`group_id`), template category,\ntag, or creation\ntime. `to` and `from` name the same ends of the message the response\ndoes, and each accepts an E.164 phone number or a business-scoped user\nID. Pair either with `direction` to search a single side of the message.\nNeither matches a group, so `group_id` is what narrows the list to one\ngroup's messages.\nPass the response's `next_cursor` back as\n`starting_after` to fetch the next page. To follow a single message's\ndelivery, use\n[Get a WhatsApp message](https://bird.com/docs/api/reference/get-whatsapp-message)\ninstead.\n\nMessages are retained for **30 days**. A `created_after` earlier than that\nis accepted and raised to the retention bound rather than rejected, so a\nwider window returns what is still retained instead of failing. There is no\nway to read messages older than the window.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "created_after", "value": "2026-05-01T00:00:00Z", "description": "Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": false, "key": "created_before", "value": "2026-06-01T00:00:00Z", "description": "Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": true, "key": "status", "value": "", "description": "Filter by status. Repeat the parameter to match any of several statuses." }, { "disabled": true, "key": "status", "value": "", "description": "Filter by status. Repeat the parameter to match any of several statuses." }, { "disabled": true, "key": "direction", "value": "", "description": "Filter by whether the business sent the message (`outbound`) or received it from the contact (`inbound`).\n" }, { "disabled": false, "key": "to", "value": "+15551234567", "description": "Filter by recipient, exact match. The recipient is the contact on an outbound message and your business number on an inbound one, matching the `to` each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so `to=` matches outbound messages only.\n" }, { "disabled": false, "key": "from", "value": "+13124495648", "description": "Filter by sender, exact match. The sender is your business number on an outbound message and the contact on an inbound one, matching the `from` each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so `from=` matches inbound messages only.\n" }, { "disabled": false, "key": "phone_number", "value": "+15551234567", "description": "Deprecated: use `to` or `from` instead, which also match a business-scoped user ID. Filters by contact phone number (E.164 exact match), in either direction.\n" }, { "disabled": false, "key": "bsuid", "value": "NL.xxxx", "description": "Filter by business-scoped user ID (Meta identifier), matching the contact in either direction. `to` and `from` also accept one, but each matches a single end of the message.\n" }, { "disabled": true, "key": "category", "value": "", "description": "Filter by category." }, { "disabled": true, "key": "group_id", "value": "", "description": "Filter by the WhatsApp group the message belongs to, in either direction: the group an outbound message was addressed to, or the group an inbound message arrived through. Matches the `group_id` on each message's `to`. It names one group, so there is no way to ask for the messages that belong to no group: omit it to list group and one-to-one messages together.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages?limit=25&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&to=+15551234567&from=+13124495648&phone_number=+15551234567&bsuid=NL.xxxx" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "f8e57b95-5acc-87d6-88a2-ae2c21495403", "name": "Paginated list of WhatsApp messages.", "originalRequest": { "name": "List WhatsApp messages", "description": { "content": "Returns the workspace's WhatsApp messages as a cursor-paginated list,\nnewest first, outbound and inbound alike. Each message carries the one\ncontent object it was built from: `template`, or free-form `text`,\n`image`, `video`, `audio`, `sticker`, `document`, `location`,\n`interactive` or `contact_cards`. An inbound message carries\n`interactive_reply` when the contact tapped a reply button or a list row,\non an interactive message or on a template's quick reply. An inbound\nmessage whose content WhatsApp models and we do not carries `unsupported`\ninstead, naming the type rather than reading back empty.\nFilter by direction, status, recipient (`to`), sender (`from`),\nbusiness-scoped user ID (`bsuid`), group (`group_id`), template category,\ntag, or creation\ntime. `to` and `from` name the same ends of the message the response\ndoes, and each accepts an E.164 phone number or a business-scoped user\nID. Pair either with `direction` to search a single side of the message.\nNeither matches a group, so `group_id` is what narrows the list to one\ngroup's messages.\nPass the response's `next_cursor` back as\n`starting_after` to fetch the next page. To follow a single message's\ndelivery, use\n[Get a WhatsApp message](https://bird.com/docs/api/reference/get-whatsapp-message)\ninstead.\n\nMessages are retained for **30 days**. A `created_after` earlier than that\nis accepted and raised to the retention bound rather than rejected, so a\nwider window returns what is still retained instead of failing. There is no\nway to read messages older than the window.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "created_after", "value": "2026-05-01T00:00:00Z", "description": "Limits the response to resources created at or after this timestamp. Combine it with `created_before` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": false, "key": "created_before", "value": "2026-06-01T00:00:00Z", "description": "Limits the response to resources created before this timestamp. Combine it with `created_after` to select a time window. Use an RFC 3339 timestamp with a timezone offset." }, { "disabled": true, "key": "status", "value": "", "description": "Filter by status. Repeat the parameter to match any of several statuses." }, { "disabled": true, "key": "status", "value": "", "description": "Filter by status. Repeat the parameter to match any of several statuses." }, { "disabled": true, "key": "direction", "value": "", "description": "Filter by whether the business sent the message (`outbound`) or received it from the contact (`inbound`).\n" }, { "disabled": false, "key": "to", "value": "+15551234567", "description": "Filter by recipient, exact match. The recipient is the contact on an outbound message and your business number on an inbound one, matching the `to` each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so `to=` matches outbound messages only.\n" }, { "disabled": false, "key": "from", "value": "+13124495648", "description": "Filter by sender, exact match. The sender is your business number on an outbound message and the contact on an inbound one, matching the `from` each message returns. Accepts an E.164 phone number, or a business-scoped user ID to name the contact. Only a contact is ever identified by a business-scoped user ID, so `from=` matches inbound messages only.\n" }, { "disabled": false, "key": "phone_number", "value": "+15551234567", "description": "Deprecated: use `to` or `from` instead, which also match a business-scoped user ID. Filters by contact phone number (E.164 exact match), in either direction.\n" }, { "disabled": false, "key": "bsuid", "value": "NL.xxxx", "description": "Filter by business-scoped user ID (Meta identifier), matching the contact in either direction. `to` and `from` also accept one, but each matches a single end of the message.\n" }, { "disabled": true, "key": "category", "value": "", "description": "Filter by category." }, { "disabled": true, "key": "group_id", "value": "", "description": "Filter by the WhatsApp group the message belongs to, in either direction: the group an outbound message was addressed to, or the group an inbound message arrived through. Matches the `group_id` on each message's `to`. It names one group, so there is no way to ask for the messages that belong to no group: omit it to list group and one-to-one messages together.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages?limit=25&created_after=2026-05-01T00:00:00Z&created_before=2026-06-01T00:00:00Z&to=+15551234567&from=+13124495648&phone_number=+15551234567&bsuid=NL.xxxx" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"wam_01kya1b3xdq7fe8m2v5t9rncgs\",\n \"direction\": \"inbound\",\n \"from\": {\n \"phone_number\": \"+15550002222\",\n \"bsuid\": \"US.AbC1\",\n \"display_name\": \"Dana Reyes\"\n },\n \"to\": {\n \"phone_number\": \"+15550001111\",\n \"group_id\": \"wag_01krdgeqcxet5s7t44vh8rt9mg\"\n },\n \"text\": {\n \"body\": \"Got it, thanks.\"\n },\n \"status\": \"received\",\n \"created_at\": \"2026-09-15T14:05:41Z\"\n },\n {\n \"id\": \"wam_01kya19eknftrs2s6p82asmvnh\",\n \"direction\": \"outbound\",\n \"from\": {\n \"phone_number\": \"+15550001111\"\n },\n \"to\": {\n \"group_id\": \"wag_01krdgeqcxet5s7t44vh8rt9mg\"\n },\n \"text\": {\n \"body\": \"The route sheet for Tuesday is up.\"\n },\n \"status\": \"delivered\",\n \"recipient_count\": 2,\n \"delivered_count\": 2,\n \"read_count\": 1,\n \"created_at\": \"2026-09-15T14:03:10Z\"\n }\n ],\n \"next_cursor\": null,\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "9513c9a8-b02d-8e4a-8e1d-fabd5b5f8b36", "name": "Send a WhatsApp message", "request": { "name": "Send a WhatsApp message", "description": { "content": "Sends one WhatsApp message to one recipient. The request carries exactly one\nkind of content: a message template, or free-form `text`, `image`, `video`,\n`audio`, `sticker`, `document`, `location`, `contact_cards` or\n`interactive`. A request carrying none is rejected with a `422`, and one\ncarrying more than one is too.\n\nA **template** is the only content WhatsApp delivers outside an open\ncustomer service window, so it is what starts a conversation. Name the\ntemplate, optionally pick its language variant, and fill its placeholders in\n`components`. A Bird-managed template selects its sender number from its\ncategory, so the request carries no `from`; a template your workspace\nauthored requires one. Browse your workspace's templates in the Bird\ndashboard.\n\n**Free-form content** is deliverable only inside an open 24-hour customer\nservice window, which the contact opens by messaging or calling you and\nresets each time they do it again. Bird tracks that window, so a send into a\nclosed one is refused with a `422` `WhatsAppServiceWindowClosed` before\nanything is created or charged;\nsend a template instead, which reopens the window once the contact replies.\nA window that closes between accept and dispatch still fails\nasynchronously, carrying `service_window_expired` on the message's\n`last_error`. Every free-form send requires `from`.\n\n**Interactive content** gives the recipient something to tap. `interactive`\nnames its kind in `type` and carries that kind's own field: reply `buttons`,\na `list` menu, a `cta_url` link button, or `cards` for a carousel;\n`location_request_message` and `request_contact_info` are each a single\nbutton asking the recipient for something, so `body_text` is the whole\nmessage. A tap on a reply button or a list row comes back as an inbound\nmessage carrying `interactive_reply`. The other kinds answer in their own\nshape: a `cta_url` link opens in the recipient's browser and sends nothing\nback, and the two request kinds come back as the thing they asked for, an\ninbound `location` or `contact_cards` message.\nInteractive content is free-form, so the customer service window and the\n`from` requirement above both apply.\n\n**Contact cards** share up to five contacts in one message. Each card's\n`name` needs `formatted_name` plus at least one other part, and a\n`phone_number` in E.164 earns that card a button opening a chat with it.\nContact cards are free-form too, so the same window and `from` rules apply.\n\n**A group send** addresses a WhatsApp group ID in `to` and carries no\n`from`: the group sends on its own number, and the response reports the\nfan-out.\n`recipient_count` is the group's membership when the send was accepted,\n`delivered_count` and `read_count` count against it, and `status` turns\n`delivered` only once every participant has it. WhatsApp delivers neither\ninteractive content nor an authentication template to a group, and a\nBird-managed template sends from a number no group is scoped to.\n\nSet `in_reply_to_message_id` to quote a message the contact sees above this\none, the way replying in the WhatsApp client does. Any content quotes, and\nthe quoted message must be one from this same conversation.\n\nThe `202` response is the accepted message, echoing the resolved content; it\nis not a delivery confirmation. Follow delivery with\n[Get a WhatsApp message](https://bird.com/docs/api/reference/get-whatsapp-message), the\nper-message timeline from\n[List events for a WhatsApp message](https://bird.com/docs/api/reference/list-whatsapp-message-events),\nor `whatsapp.*` webhook events.\n\nEach of these returns a `422`:\n\n- A template slug or language the catalogue does not stock.\n- Parameter values that do not match the template's declared placeholders.\n- A `from` this workspace cannot send from.\n- A recipient that is neither a valid phone number nor a business-scoped user ID.\n- Free-form content sent into a closed customer service window\n (`WhatsAppServiceWindowClosed`).\n- Interactive content or an authentication template addressed to a group\n (`WhatsAppGroupContentNotSupported`).\n\nA group `to` naming no group this workspace holds fails with a `404`\n`WhatsAppGroupNotFound`, and one whose group is not active with a `409`\n`WhatsAppGroupNotActive`. A send from a workspace with no wallet balance\nfails with a `402`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"+31612345678\",\n \"template\": {\n \"slug\": \"bird_otp\",\n \"language\": \"en\",\n \"components\": [\n {\n \"type\": \"body\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"1234\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"1234\"\n }\n ]\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "0ae95100-2efe-8642-85f8-86657f2429c8", "name": "Message accepted for asynchronous delivery.", "originalRequest": { "name": "Send a WhatsApp message", "description": { "content": "Sends one WhatsApp message to one recipient. The request carries exactly one\nkind of content: a message template, or free-form `text`, `image`, `video`,\n`audio`, `sticker`, `document`, `location`, `contact_cards` or\n`interactive`. A request carrying none is rejected with a `422`, and one\ncarrying more than one is too.\n\nA **template** is the only content WhatsApp delivers outside an open\ncustomer service window, so it is what starts a conversation. Name the\ntemplate, optionally pick its language variant, and fill its placeholders in\n`components`. A Bird-managed template selects its sender number from its\ncategory, so the request carries no `from`; a template your workspace\nauthored requires one. Browse your workspace's templates in the Bird\ndashboard.\n\n**Free-form content** is deliverable only inside an open 24-hour customer\nservice window, which the contact opens by messaging or calling you and\nresets each time they do it again. Bird tracks that window, so a send into a\nclosed one is refused with a `422` `WhatsAppServiceWindowClosed` before\nanything is created or charged;\nsend a template instead, which reopens the window once the contact replies.\nA window that closes between accept and dispatch still fails\nasynchronously, carrying `service_window_expired` on the message's\n`last_error`. Every free-form send requires `from`.\n\n**Interactive content** gives the recipient something to tap. `interactive`\nnames its kind in `type` and carries that kind's own field: reply `buttons`,\na `list` menu, a `cta_url` link button, or `cards` for a carousel;\n`location_request_message` and `request_contact_info` are each a single\nbutton asking the recipient for something, so `body_text` is the whole\nmessage. A tap on a reply button or a list row comes back as an inbound\nmessage carrying `interactive_reply`. The other kinds answer in their own\nshape: a `cta_url` link opens in the recipient's browser and sends nothing\nback, and the two request kinds come back as the thing they asked for, an\ninbound `location` or `contact_cards` message.\nInteractive content is free-form, so the customer service window and the\n`from` requirement above both apply.\n\n**Contact cards** share up to five contacts in one message. Each card's\n`name` needs `formatted_name` plus at least one other part, and a\n`phone_number` in E.164 earns that card a button opening a chat with it.\nContact cards are free-form too, so the same window and `from` rules apply.\n\n**A group send** addresses a WhatsApp group ID in `to` and carries no\n`from`: the group sends on its own number, and the response reports the\nfan-out.\n`recipient_count` is the group's membership when the send was accepted,\n`delivered_count` and `read_count` count against it, and `status` turns\n`delivered` only once every participant has it. WhatsApp delivers neither\ninteractive content nor an authentication template to a group, and a\nBird-managed template sends from a number no group is scoped to.\n\nSet `in_reply_to_message_id` to quote a message the contact sees above this\none, the way replying in the WhatsApp client does. Any content quotes, and\nthe quoted message must be one from this same conversation.\n\nThe `202` response is the accepted message, echoing the resolved content; it\nis not a delivery confirmation. Follow delivery with\n[Get a WhatsApp message](https://bird.com/docs/api/reference/get-whatsapp-message), the\nper-message timeline from\n[List events for a WhatsApp message](https://bird.com/docs/api/reference/list-whatsapp-message-events),\nor `whatsapp.*` webhook events.\n\nEach of these returns a `422`:\n\n- A template slug or language the catalogue does not stock.\n- Parameter values that do not match the template's declared placeholders.\n- A `from` this workspace cannot send from.\n- A recipient that is neither a valid phone number nor a business-scoped user ID.\n- Free-form content sent into a closed customer service window\n (`WhatsAppServiceWindowClosed`).\n- Interactive content or an authentication template addressed to a group\n (`WhatsAppGroupContentNotSupported`).\n\nA group `to` naming no group this workspace holds fails with a `404`\n`WhatsAppGroupNotFound`, and one whose group is not active with a `409`\n`WhatsAppGroupNotActive`. A send from a workspace with no wallet balance\nfails with a `402`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"+31612345678\",\n \"template\": {\n \"slug\": \"bird_otp\",\n \"language\": \"en\",\n \"components\": [\n {\n \"type\": \"body\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"1234\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"1234\"\n }\n ]\n }\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"wam_01kya19eknftrs2s6p82asmvnh\",\n \"direction\": \"outbound\",\n \"from\": {\n \"phone_number\": \"+15550001111\"\n },\n \"to\": {\n \"group_id\": \"wag_01krdgeqcxet5s7t44vh8rt9mg\"\n },\n \"text\": {\n \"body\": \"The route sheet for Tuesday is up.\"\n },\n \"status\": \"accepted\",\n \"recipient_count\": 2,\n \"delivered_count\": 0,\n \"read_count\": 0,\n \"created_at\": \"2026-09-15T14:03:10Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "8ace2815-cde9-80be-83ee-7e71ea45fb7d", "name": "Get a WhatsApp message", "request": { "name": "Get a WhatsApp message", "description": { "content": "Returns a single WhatsApp message: its current delivery status, per-stage timestamps (`sent_at`, `delivered_at`, `read_at`), and failure detail when it failed. It carries the one content object it was built from: `template`, or free-form `text`, `image`, `video`, `audio`, `sticker`, `document`, `location`, `interactive` or `contact_cards`. An inbound message carries `interactive_reply` when the contact tapped a reply button or a list row. An inbound message whose content WhatsApp models and we do not carries `unsupported` instead, naming the type rather than reading back empty. The `status` advances asynchronously as delivery progresses, so poll this endpoint (or subscribe to `whatsapp.*` webhook events) after a send to confirm delivery. For the per-event timeline, use [List events for a WhatsApp message](https://bird.com/docs/api/reference/list-whatsapp-message-events) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message, as returned in the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "bf2e1f28-af45-8588-8a2a-08342e8d9784", "name": "WhatsApp message object.", "originalRequest": { "name": "Get a WhatsApp message", "description": { "content": "Returns a single WhatsApp message: its current delivery status, per-stage timestamps (`sent_at`, `delivered_at`, `read_at`), and failure detail when it failed. It carries the one content object it was built from: `template`, or free-form `text`, `image`, `video`, `audio`, `sticker`, `document`, `location`, `interactive` or `contact_cards`. An inbound message carries `interactive_reply` when the contact tapped a reply button or a list row. An inbound message whose content WhatsApp models and we do not carries `unsupported` instead, naming the type rather than reading back empty. The `status` advances asynchronously as delivery progresses, so poll this endpoint (or subscribe to `whatsapp.*` webhook events) after a send to confirm delivery. For the per-event timeline, use [List events for a WhatsApp message](https://bird.com/docs/api/reference/list-whatsapp-message-events) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message, as returned in the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"wam_01kya19eknftrs2s6p82asmvnh\",\n \"direction\": \"outbound\",\n \"from\": {\n \"phone_number\": \"+15550001111\"\n },\n \"to\": {\n \"group_id\": \"wag_01krdgeqcxet5s7t44vh8rt9mg\"\n },\n \"text\": {\n \"body\": \"Tuesday's route sheet is up.\"\n },\n \"status\": \"delivered\",\n \"recipient_count\": 2,\n \"delivered_count\": 2,\n \"read_count\": 2,\n \"created_at\": \"2026-09-15T14:03:10Z\",\n \"sent_at\": \"2026-09-15T14:03:11Z\",\n \"delivered_at\": \"2026-09-15T14:03:12Z\",\n \"read_at\": \"2026-09-15T14:04:02Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "b610643c-98ed-8ef4-85b1-ec5f235c8c5f", "name": "Mark a WhatsApp message as read", "request": { "name": "Mark a WhatsApp message as read", "description": { "content": "Marks an inbound WhatsApp message as read, showing the contact the blue\nticks. WhatsApp also marks every earlier message in that conversation read.\nThis does not change the workspace inbox unread count. Use the conversation\nupdate endpoint with `read` to acknowledge messages in the inbox.\n\nPass `typing_indicator: true` to show a typing indicator as well. WhatsApp\nclears it when you send your next message, or after 25 seconds, whichever\ncomes first, and there is no call to clear it early, so ask for one only\nwhen you are about to reply. WhatsApp cannot show a typing indicator without\na read receipt, so both arrive together.\n\nThe acknowledgement is sent asynchronously: a `202` means Bird accepted the\nrequest, not that WhatsApp has shown it. Nothing reports back, because\nWhatsApp publishes no delivery, status or failure callback for an\nacknowledgement, so there is nothing to poll and no webhook event.\nRepeating the call is safe, and each call restarts the 25-second typing\nwindow. To refresh the indicator, send a fresh `Idempotency-Key` or none at\nall: a replayed key answers from the stored response without acknowledging\nanything again.\n\nOnly an inbound message can be marked read. WhatsApp allows this for 30\ndays after receipt, but Bird keeps the provider id a receipt needs for 15\ndays, so a message older than that answers `404`. A message Bird sent, or\none that never reached WhatsApp, answers `422`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "read" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the inbound message to acknowledge." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/read" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"typing_indicator\": true\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "2e504115-b95a-84a2-8085-cc2d76879e2b", "name": "Acknowledgement accepted for asynchronous delivery.", "originalRequest": { "name": "Mark a WhatsApp message as read", "description": { "content": "Marks an inbound WhatsApp message as read, showing the contact the blue\nticks. WhatsApp also marks every earlier message in that conversation read.\nThis does not change the workspace inbox unread count. Use the conversation\nupdate endpoint with `read` to acknowledge messages in the inbox.\n\nPass `typing_indicator: true` to show a typing indicator as well. WhatsApp\nclears it when you send your next message, or after 25 seconds, whichever\ncomes first, and there is no call to clear it early, so ask for one only\nwhen you are about to reply. WhatsApp cannot show a typing indicator without\na read receipt, so both arrive together.\n\nThe acknowledgement is sent asynchronously: a `202` means Bird accepted the\nrequest, not that WhatsApp has shown it. Nothing reports back, because\nWhatsApp publishes no delivery, status or failure callback for an\nacknowledgement, so there is nothing to poll and no webhook event.\nRepeating the call is safe, and each call restarts the 25-second typing\nwindow. To refresh the indicator, send a fresh `Idempotency-Key` or none at\nall: a replayed key answers from the stored response without acknowledging\nanything again.\n\nOnly an inbound message can be marked read. WhatsApp allows this for 30\ndays after receipt, but Bird keeps the provider id a receipt needs for 15\ndays, so a message older than that answers `404`. A message Bird sent, or\none that never reached WhatsApp, answers `422`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "read" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the inbound message to acknowledge." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/read" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"typing_indicator\": true\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"typing_indicator\": true\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "117a986f-571d-8b1a-8271-be715467f4fe", "name": "List events for a WhatsApp message", "request": { "name": "List events for a WhatsApp message", "description": { "content": "Returns a WhatsApp message's lifecycle events in chronological order, one entry per delivery transition (`whatsapp.accepted`, `whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`). The timeline is bounded and returned in full, so this list is not paginated; an unknown message ID returns `404`. For the message's current state in a single field, use [Get a WhatsApp message](https://bird.com/docs/api/reference/get-whatsapp-message) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "type", "value": "", "description": "Keep only events of this exact type (for example `whatsapp.delivered` or `whatsapp.failed`). Omit for the full timeline.\n" } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message, as returned in the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/events" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "3d11619f-457c-8d28-83bc-d21ca63ac821", "name": "Event timeline for this WhatsApp message.", "originalRequest": { "name": "List events for a WhatsApp message", "description": { "content": "Returns a WhatsApp message's lifecycle events in chronological order, one entry per delivery transition (`whatsapp.accepted`, `whatsapp.sent`, `whatsapp.delivered`, `whatsapp.read`, `whatsapp.failed`). The timeline is bounded and returned in full, so this list is not paginated; an unknown message ID returns `404`. For the message's current state in a single field, use [Get a WhatsApp message](https://bird.com/docs/api/reference/get-whatsapp-message) instead.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "type", "value": "", "description": "Keep only events of this exact type (for example `whatsapp.delivered` or `whatsapp.failed`). Omit for the full timeline.\n" } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message, as returned in the send response's `id` field." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/events" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"ev_01kya19f8p2hs5w1y7k4cmqrtv\",\n \"type\": \"whatsapp.sent\",\n \"occurred_at\": \"2026-09-15T14:03:11Z\"\n },\n {\n \"id\": \"ev_01kya19f2m8xqe4v0t6r3bnpcd\",\n \"type\": \"whatsapp.delivered\",\n \"occurred_at\": \"2026-09-15T14:03:12Z\",\n \"recipient\": {\n \"phone_number\": \"+15550002222\",\n \"bsuid\": \"US.AbC1\"\n }\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "1dfface8-2110-8c45-83f2-7bd86443ffec", "name": "Get a WhatsApp message's media", "request": { "name": "Get a WhatsApp message's media", "description": { "content": "Redirects to a short-lived URL for the media on a received WhatsApp message.\nInbound media is stored because WhatsApp's own URL is not fetchable\nwithout our credentials; this endpoint is what the `url` on the message's\n`image`, `video`, `audio`, `sticker` or `document` points at. The bytes\nlive in object storage and are served straight from there, so they never\ntransit the API.\n\nThe response is a `302` whose `Location` is that pre-authorized storage URL,\nvalid for 15 minutes; your client must follow redirects. The `Authorization`\nheader must be absent from the request that fetches that URL: a client that\nattaches credentials centrally, at its transport, interceptor or middleware\nlayer rather than per request, re-adds the header on every hop including the\nredirect, so the storage URL must be fetched with a client that carries\nnone.\n\nMedia is kept for 30 days after the message is received, and the message\nitself is kept longer. A message older than that still lists its media's\n`mime_type` and `caption`, and this operation returns `410` once the bytes\nhave expired. Outbound messages have no media to serve.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "media", ":media_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) WhatsApp message ID." }, { "disabled": false, "type": "any", "value": "", "key": "media_id", "description": "(Required) Media ID, as returned in `id` on the message's content object." } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/media/:media_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d7dbfbac-fc91-8b59-834e-24a72b35d006", "name": "React to a WhatsApp message", "request": { "name": "React to a WhatsApp message", "description": { "content": "Places an emoji reaction on a message this workspace received, the same way\ntapping and holding a message in WhatsApp does.\n\nYou hold at most one reaction per message, so this replaces your existing\none rather than adding another. To take a reaction back entirely, delete it.\n\nThe `202` means the reaction was accepted, not that WhatsApp applied it.\nReactions carry no delivery or read receipt, so the furthest one gets is\nsent. Read the message's `reactions` for what currently stands, or\n[List reaction events for a WhatsApp message](https://bird.com/docs/api/reference/list-whatsapp-message-reaction-events)\nfor what became of each change, including one WhatsApp refused.\n\nEach of these returns a `422`:\n\n- A message this workspace sent. This endpoint places reactions on messages\n the contact sent; reacting to your own outbound message is not supported.\n- More than one emoji, since WhatsApp takes exactly one.\n\nA message Bird can no longer resolve returns a `404` instead. WhatsApp\naccepts a reaction on a message up to 30 days old, but Bird keeps the\nprovider id a reaction needs for **15 days**, so that is the practical age\nlimit. The message and its reaction log stay readable for 30; only the id\na placement needs is gone.\n\nReacting to a message received in a group addresses the group, so the\ngroup's own state applies: a group this workspace no longer holds returns\na `404` `WhatsAppGroupNotFound`, and one that is not active a `409`\n`WhatsAppGroupNotActive`.\n\nReactions are not charged for.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "reaction" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message to react to, as returned in the `id` field of the message. Must be a message this workspace received.\n" } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/reaction" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PUT", "body": { "mode": "raw", "raw": "{\n \"emoji\": \"👍\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "1ac4c6cb-3427-8882-8d97-f9ec3fd26e00", "name": "Reaction accepted; WhatsApp applies it asynchronously.", "originalRequest": { "name": "React to a WhatsApp message", "description": { "content": "Places an emoji reaction on a message this workspace received, the same way\ntapping and holding a message in WhatsApp does.\n\nYou hold at most one reaction per message, so this replaces your existing\none rather than adding another. To take a reaction back entirely, delete it.\n\nThe `202` means the reaction was accepted, not that WhatsApp applied it.\nReactions carry no delivery or read receipt, so the furthest one gets is\nsent. Read the message's `reactions` for what currently stands, or\n[List reaction events for a WhatsApp message](https://bird.com/docs/api/reference/list-whatsapp-message-reaction-events)\nfor what became of each change, including one WhatsApp refused.\n\nEach of these returns a `422`:\n\n- A message this workspace sent. This endpoint places reactions on messages\n the contact sent; reacting to your own outbound message is not supported.\n- More than one emoji, since WhatsApp takes exactly one.\n\nA message Bird can no longer resolve returns a `404` instead. WhatsApp\naccepts a reaction on a message up to 30 days old, but Bird keeps the\nprovider id a reaction needs for **15 days**, so that is the practical age\nlimit. The message and its reaction log stay readable for 30; only the id\na placement needs is gone.\n\nReacting to a message received in a group addresses the group, so the\ngroup's own state applies: a group this workspace no longer holds returns\na `404` `WhatsAppGroupNotFound`, and one that is not active a `409`\n`WhatsAppGroupNotActive`.\n\nReactions are not charged for.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "reaction" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message to react to, as returned in the `id` field of the message. Must be a message this workspace received.\n" } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/reaction" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PUT", "body": { "mode": "raw", "raw": "{\n \"emoji\": \"👍\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"war_01krdgeqcxet5s7t44vh8rt9mg\",\n \"emoji\": \"👍\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "c7c2d8e4-ef2b-8695-8036-7d8a81dfd67b", "name": "Remove your reaction from a WhatsApp message", "request": { "name": "Remove your reaction from a WhatsApp message", "description": { "content": "Takes back the reaction this workspace placed on a message, the same way\ntapping your own reaction in WhatsApp does. Only your own reaction can be\nremoved; one the contact placed is theirs to take back.\n\nRemoving a reaction from a message you have not reacted to changes nothing\nand still answers `202`, so a repeated call is safe.\n\nA removal travels the same path as placing a reaction, so it is refused on\nthe same grounds. A message this workspace sent returns a `422`: it could\nnever have carried a reaction of ours to remove, since placing one there is\nnot supported either.\n\nA message Bird can no longer resolve returns a `404` instead, on the same\n15-day retention a placement is bounded by. A reaction on a message\nreceived in a group addresses the group, so a group this workspace no\nlonger holds returns a `404` `WhatsAppGroupNotFound` and one that is not\nactive a `409` `WhatsAppGroupNotActive`, the same as placing one does.\n\nThe `202` is the removal accepted rather than applied. The reaction stays in\nthe message's `reactions` until WhatsApp confirms the removal and then drops\nout, so one on its way off reads as still standing rather than disappearing\nbefore it is gone.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "reaction" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message to take your reaction off, as returned in the `id` field of the message.\n" } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/reaction" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "response": [ { "id": "3860568a-162d-84c2-8425-3df029715d33", "name": "Removal accepted. No body: the reaction is still standing at this point, and on a message this workspace never reacted to there is nothing to return. Read the message's `reactions` to see it go.\n", "originalRequest": { "name": "Remove your reaction from a WhatsApp message", "description": { "content": "Takes back the reaction this workspace placed on a message, the same way\ntapping your own reaction in WhatsApp does. Only your own reaction can be\nremoved; one the contact placed is theirs to take back.\n\nRemoving a reaction from a message you have not reacted to changes nothing\nand still answers `202`, so a repeated call is safe.\n\nA removal travels the same path as placing a reaction, so it is refused on\nthe same grounds. A message this workspace sent returns a `422`: it could\nnever have carried a reaction of ours to remove, since placing one there is\nnot supported either.\n\nA message Bird can no longer resolve returns a `404` instead, on the same\n15-day retention a placement is bounded by. A reaction on a message\nreceived in a group addresses the group, so a group this workspace no\nlonger holds returns a `404` `WhatsAppGroupNotFound` and one that is not\nactive a `409` `WhatsAppGroupNotActive`, the same as placing one does.\n\nThe `202` is the removal accepted rather than applied. The reaction stays in\nthe message's `reactions` until WhatsApp confirms the removal and then drops\nout, so one on its way off reads as still standing rather than disappearing\nbefore it is gone.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "reaction" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message to take your reaction off, as returned in the `id` field of the message.\n" } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/reaction" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "645b2649-0f24-85df-8db9-6e9ca3bb140d", "name": "List reaction events for a WhatsApp message", "request": { "name": "List reaction events for a WhatsApp message", "description": { "content": "Returns the changes made to this message's reactions as a cursor-paginated\nlist, newest first: each emoji placed, each one replaced by a different\nemoji, and each one taken back. Entries are never edited, so a contact who\nreacts, changes their mind and then removes it leaves three of them.\n\nOne case is missing rather than recorded. A reaction is matched to the\nmessage it was placed on through a provider id we keep for 15 days, while\nWhatsApp accepts a reaction on a message up to 30 days old, so one placed on\na message older than that cannot be matched and is recorded nowhere: not\nhere, and not in the message's `reactions`.\n\nUse this to show who reacted and when, or to find out what became of a\nreaction that never appeared: a `failed` or `rejected` entry carries the\nreason on `error`. For what currently stands on the message, read its\n`reactions`, which folds this log down to one entry per sender.\n\nPass the response's `next_cursor` back as `starting_after` to fetch the next\npage.\n\nReaction events are kept for **30 days**, counted from when the message they\nbelong to was accepted rather than from the reaction itself. They therefore\ngo at about the same time as the message, not 30 days after the last\nreaction on it.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "reaction-events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose reactions to read, as returned in the `id` field of the message.\n" } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/reaction-events?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "6cae84b2-3c9c-8d3b-8fa8-17dcfc064c53", "name": "Paginated list of reaction changes for this WhatsApp message.", "originalRequest": { "name": "List reaction events for a WhatsApp message", "description": { "content": "Returns the changes made to this message's reactions as a cursor-paginated\nlist, newest first: each emoji placed, each one replaced by a different\nemoji, and each one taken back. Entries are never edited, so a contact who\nreacts, changes their mind and then removes it leaves three of them.\n\nOne case is missing rather than recorded. A reaction is matched to the\nmessage it was placed on through a provider id we keep for 15 days, while\nWhatsApp accepts a reaction on a message up to 30 days old, so one placed on\na message older than that cannot be matched and is recorded nowhere: not\nhere, and not in the message's `reactions`.\n\nUse this to show who reacted and when, or to find out what became of a\nreaction that never appeared: a `failed` or `rejected` entry carries the\nreason on `error`. For what currently stands on the message, read its\n`reactions`, which folds this log down to one entry per sender.\n\nPass the response's `next_cursor` back as `starting_after` to fetch the next\npage.\n\nReaction events are kept for **30 days**, counted from when the message they\nbelong to was accepted rather than from the reaction itself. They therefore\ngo at about the same time as the message, not 30 days after the last\nreaction on it.\n", "type": "text/plain" }, "url": { "path": [ "v1", "whatsapp", "messages", ":message_id", "reaction-events" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "message_id", "description": "(Required) ID of the message whose reactions to read, as returned in the `id` field of the message.\n" } ], "raw": "{{BIRD_API_URL}}/v1/whatsapp/messages/:message_id/reaction-events?limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"war_01krdgeqcxet5s7t44vh8rt9mh\",\n \"emoji\": \"🎉\",\n \"status\": \"rejected\",\n \"from\": {\n \"phone_number\": \"+13124495569\"\n },\n \"error\": {\n \"code\": \"internal_error\",\n \"description\": \"the receiving number is no longer connected\",\n \"occurred_at\": \"2026-08-28T19:04:22Z\"\n },\n \"occurred_at\": \"2026-08-28T19:04:22Z\"\n },\n {\n \"id\": \"war_01krdgeqcxet5s7t44vh8rt9mg\",\n \"emoji\": \"👍\",\n \"status\": \"received\",\n \"from\": {\n \"phone_number\": \"+14155550100\",\n \"bsuid\": \"US.13491208655302741918\"\n },\n \"occurred_at\": \"2026-08-28T19:01:10Z\"\n }\n ],\n \"next_cursor\": null,\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiMjAyNi0wOC0yOFQxOTowNDoyMloiLCJpIjoiMDE5ZTFiMDctNWQ5ZC03NjhiLTkzZTgtODRkYzUxOGQyNjkxIn0\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "7b20c8d7-6866-8ced-85f6-fdc251ad9a8c", "name": "webhooks", "description": { "content": "Webhook endpoint management.", "type": "text/plain" }, "item": [ { "id": "e4b772fa-1107-8783-8883-58d8f0a01b93", "name": "Create a webhook endpoint", "request": { "name": "Create a webhook endpoint", "description": { "content": "Registers an `active` webhook endpoint that receives the event types in `events` as signed HTTPS `POST` requests. See the [webhooks guide](https://bird.com/docs/guides/webhooks) for delivery, signing, and retry behavior.\n\nThe `201` response is the only response that includes the signing secret (`whsec_` prefix). Store it immediately; if it is lost, [rotate the signing secret](https://bird.com/docs/api/reference/rotate-webhook-secret).\n\nA non-HTTPS or non-public `url`, an unknown event type, or exceeding the organization's endpoint limit returns `422`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/webhooks" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/webhooks/bird\",\n \"events\": [\n \"email.delivered\",\n \"email.bounced\"\n ],\n \"description\": \"Production delivery + bounce notifications\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "0e75dc1c-3859-8cd9-8c09-ff6c3d622a4a", "name": "Created webhook endpoint, including its one-time signing secret.", "originalRequest": { "name": "Create a webhook endpoint", "description": { "content": "Registers an `active` webhook endpoint that receives the event types in `events` as signed HTTPS `POST` requests. See the [webhooks guide](https://bird.com/docs/guides/webhooks) for delivery, signing, and retry behavior.\n\nThe `201` response is the only response that includes the signing secret (`whsec_` prefix). Store it immediately; if it is lost, [rotate the signing secret](https://bird.com/docs/api/reference/rotate-webhook-secret).\n\nA non-HTTPS or non-public `url`, an unknown event type, or exceeding the organization's endpoint limit returns `422`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/webhooks" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/webhooks/bird\",\n \"events\": [\n \"email.delivered\",\n \"email.bounced\"\n ],\n \"description\": \"Production delivery + bounce notifications\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Created", "code": 201, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"whk_01krdgeqcxet5s7t44vh8rt9mg\",\n \"url\": \"https://example.com/webhook\",\n \"description\": \"Production webhook endpoint\",\n \"filter\": null,\n \"events\": [\n \"email.delivered\",\n \"email.bounced\"\n ],\n \"status\": \"active\",\n \"destination\": {\n \"type\": \"webhook\"\n },\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\",\n \"secret\": \"whsec_base64encodedvalue\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "3dadc3e8-1a19-88b0-89b0-2aee56b78a1e", "name": "List webhook endpoints", "request": { "name": "List webhook endpoints", "description": { "content": "Returns the workspace's webhook endpoints as a cursor-paginated list, newest first by default. Endpoint objects never include the signing secret; to inspect a single endpoint, use [Get a webhook endpoint](https://bird.com/docs/api/reference/get-webhook).\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "sort", "value": "" }, { "disabled": false, "key": "order", "value": "desc", "description": "Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.\n" }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "include_total", "value": "false", "description": "When true, the response includes a `total` field with the total number of items matching the request's filters across all pages." }, { "disabled": false, "key": "url", "value": "https://hooks.zapier.com/hooks/catch/123/abc/", "description": "Only endpoints delivering to exactly this URL. Several endpoints can share a URL, so this finds matches for a setup to reuse; it does not prevent a duplicate.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/webhooks?order=desc&limit=25&include_total=false&url=https://hooks.zapier.com/hooks/catch/123/abc/" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "b3c7c160-ff13-8d4f-8838-76b553ede799", "name": "Paginated list of webhook endpoints.", "originalRequest": { "name": "List webhook endpoints", "description": { "content": "Returns the workspace's webhook endpoints as a cursor-paginated list, newest first by default. Endpoint objects never include the signing secret; to inspect a single endpoint, use [Get a webhook endpoint](https://bird.com/docs/api/reference/get-webhook).\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "sort", "value": "" }, { "disabled": false, "key": "order", "value": "desc", "description": "Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.\n" }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." }, { "disabled": false, "key": "include_total", "value": "false", "description": "When true, the response includes a `total` field with the total number of items matching the request's filters across all pages." }, { "disabled": false, "key": "url", "value": "https://hooks.zapier.com/hooks/catch/123/abc/", "description": "Only endpoints delivering to exactly this URL. Several endpoints can share a URL, so this finds matches for a setup to reuse; it does not prevent a duplicate.\n" } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/webhooks?order=desc&limit=25&include_total=false&url=https://hooks.zapier.com/hooks/catch/123/abc/" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"whk_01krdgeqcxet5s7t44vh8rt9mg\",\n \"url\": \"https://example.com/webhook\",\n \"description\": \"Production webhook endpoint\",\n \"filter\": null,\n \"events\": [\n \"email.delivered\",\n \"email.bounced\"\n ],\n \"status\": \"active\",\n \"destination\": {\n \"type\": \"webhook\"\n },\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "b03cb202-cd87-8766-8a49-f2d7799ba14f", "name": "Get a webhook endpoint", "request": { "name": "Get a webhook endpoint", "description": { "content": "Returns one webhook endpoint's configuration and current delivery `status`, including its URL and subscribed event types. The signing secret is never included; if you lost it, mint a new one with [Rotate webhook signing secret](https://bird.com/docs/api/reference/rotate-webhook-secret).\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "84ea2c6d-0d90-8221-8b80-e0831a24c35a", "name": "Webhook endpoint with its current URL, subscriptions, and status.", "originalRequest": { "name": "Get a webhook endpoint", "description": { "content": "Returns one webhook endpoint's configuration and current delivery `status`, including its URL and subscribed event types. The signing secret is never included; if you lost it, mint a new one with [Rotate webhook signing secret](https://bird.com/docs/api/reference/rotate-webhook-secret).\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"whk_01krdgeqcxet5s7t44vh8rt9mg\",\n \"url\": \"https://example.com/webhook\",\n \"description\": \"Production webhook endpoint\",\n \"filter\": null,\n \"events\": [\n \"email.delivered\",\n \"email.bounced\"\n ],\n \"status\": \"active\",\n \"destination\": {\n \"type\": \"webhook\"\n },\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "19860f89-e109-8e7d-8a0a-024fcd7543b4", "name": "Update a webhook endpoint", "request": { "name": "Update a webhook endpoint", "description": { "content": "Updates the webhook endpoint. Only the fields you send change: `events` replaces the\nwhole subscription set, and `status` pauses or re-enables delivery.\n\nThe `200` response is the updated endpoint. Invalid input (a non-HTTPS or non-public\n`url`, an event type outside the catalog) returns a `422`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/webhook\",\n \"description\": \"Updated webhook endpoint\",\n \"events\": [\n \"email.delivered\",\n \"email.bounced\",\n \"email.complained\"\n ],\n \"status\": \"active\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "f87c2a46-f69c-82f3-88f9-971d78413d84", "name": "Webhook endpoint after the update.", "originalRequest": { "name": "Update a webhook endpoint", "description": { "content": "Updates the webhook endpoint. Only the fields you send change: `events` replaces the\nwhole subscription set, and `status` pauses or re-enables delivery.\n\nThe `200` response is the updated endpoint. Invalid input (a non-HTTPS or non-public\n`url`, an event type outside the catalog) returns a `422`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "PATCH", "body": { "mode": "raw", "raw": "{\n \"url\": \"https://example.com/webhook\",\n \"description\": \"Updated webhook endpoint\",\n \"events\": [\n \"email.delivered\",\n \"email.bounced\",\n \"email.complained\"\n ],\n \"status\": \"active\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"whk_01krdgeqcxet5s7t44vh8rt9mg\",\n \"url\": \"https://example.com/webhook\",\n \"description\": \"Production webhook endpoint\",\n \"filter\": null,\n \"events\": [\n \"email.delivered\",\n \"email.bounced\"\n ],\n \"status\": \"active\",\n \"destination\": {\n \"type\": \"webhook\"\n },\n \"created_at\": \"2026-05-20T09:14:52Z\",\n \"updated_at\": \"2026-05-25T16:42:01Z\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "88b5418f-9ce0-8d0b-8114-5d4ffc240c37", "name": "Delete a webhook endpoint", "request": { "name": "Delete a webhook endpoint", "description": { "content": "Permanently removes the webhook endpoint and stops all deliveries to it, including retries of earlier failed deliveries. This cannot be undone: recreating an endpoint later mints a new `id` and signing secret. To stop deliveries temporarily instead, set `status` to `paused` with [Update a webhook endpoint](https://bird.com/docs/api/reference/update-webhook).\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "response": [ { "id": "742baa24-fe60-8a32-8440-80789512687b", "name": "Webhook endpoint deleted.", "originalRequest": { "name": "Delete a webhook endpoint", "description": { "content": "Permanently removes the webhook endpoint and stops all deliveries to it, including retries of earlier failed deliveries. This cannot be undone: recreating an endpoint later mints a new `id` and signing secret. To stop deliveries temporarily instead, set `status` to `paused` with [Update a webhook endpoint](https://bird.com/docs/api/reference/update-webhook).\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "DELETE" }, "status": "No Content", "code": 204, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "9bc185ef-2dce-830a-8846-04cdb85673b9", "name": "Rotate webhook signing secret", "request": { "name": "Rotate webhook signing secret", "description": { "content": "Generates a new signing secret for the endpoint and returns it exactly once: store it\nimmediately, it cannot be retrieved after this response. For 24 hours every delivery\nis signed with both the old and the new secret, so a receiver verifying with either\nkeeps working while you roll the new one out. After the window the old secret stops\nsigning. Verification details are in the [webhooks guide](https://bird.com/docs/guides/webhooks).\n\nAn endpoint holds at most 5 concurrently valid secrets, so rotating repeatedly within\nthe overlap window fails with `WebhookTooManySecrets` until an older secret expires.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "rotate-secret" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/rotate-secret" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "response": [ { "id": "df2c4618-21cd-89c7-8857-739e3c69634c", "name": "New signing secret.", "originalRequest": { "name": "Rotate webhook signing secret", "description": { "content": "Generates a new signing secret for the endpoint and returns it exactly once: store it\nimmediately, it cannot be retrieved after this response. For 24 hours every delivery\nis signed with both the old and the new secret, so a receiver verifying with either\nkeeps working while you roll the new one out. After the window the old secret stops\nsigning. Verification details are in the [webhooks guide](https://bird.com/docs/guides/webhooks).\n\nAn endpoint holds at most 5 concurrently valid secrets, so rotating repeatedly within\nthe overlap window fails with `WebhookTooManySecrets` until an older secret expires.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "rotate-secret" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/rotate-secret" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"secret\": \"whsec_newbase64encodedvalue\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f0c41b04-d3a2-82aa-8ec3-c185f6aca4e4", "name": "Test a webhook with a sample event", "request": { "name": "Test a webhook with a sample event", "description": { "content": "Sends a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency. An unreachable endpoint returns `status: failed` in the response body. The endpoint has 10 seconds to respond.\n\nThe body is a minimal JSON object with the event `type`, signed like a real delivery. It does not mirror that event's payload. Tests work on paused endpoints and do not appear in [List delivery attempts](https://bird.com/docs/api/reference/list-webhook-attempts).\n\nThe operation returns `412` if the endpoint lacks a valid signing secret or, when `event_type` is omitted, has no subscribed event type to use.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "test" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/test" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"event_type\": \"email.delivered\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "50c95192-96f5-8bc3-85f1-b09a69adba15", "name": "The test result, including whether your endpoint accepted the event.", "originalRequest": { "name": "Test a webhook with a sample event", "description": { "content": "Sends a signed synthetic event and returns whether your endpoint accepted it, its HTTP status, and the round-trip latency. An unreachable endpoint returns `status: failed` in the response body. The endpoint has 10 seconds to respond.\n\nThe body is a minimal JSON object with the event `type`, signed like a real delivery. It does not mirror that event's payload. Tests work on paused endpoints and do not appear in [List delivery attempts](https://bird.com/docs/api/reference/list-webhook-attempts).\n\nThe operation returns `412` if the endpoint lacks a valid signing secret or, when `event_type` is omitted, has no subscribed event type to use.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "test" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/test" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"event_type\": \"email.delivered\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"status\": \"delivered\",\n \"response_status_code\": 200,\n \"response_body\": \"OK\",\n \"response_duration_ms\": 142,\n \"event_payload\": {\n \"type\": \"amb.accepted\",\n \"timestamp\": \"2026-09-25T12:00:00Z\",\n \"data\": {\n \"workspace_id\": \"ws_01krdgeqcxet5s7t44vh8rt9mg\",\n \"message\": {\n \"id\": \"amb_01krdgeqcxet5s7t44vh8rt9mg\",\n \"conversation_id\": \"acv_01krdgeqcxet5s7t44vh8rt9mg\",\n \"business_account_id\": \"abz_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"status\": \"accepted\",\n \"kind\": \"text\",\n \"source\": \"operator\",\n \"in_reply_to_message_id\": \"amb_01krdgeqcxet5s7t44vh8rt9mg\",\n \"locale\": \"en_US\",\n \"category\": \"order_update\",\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"cost\": {\n \"amount\": \"0.00990\",\n \"currency_code\": \"USD\",\n \"transaction_amount\": \"0.00790\",\n \"passthrough_amount\": \"0.00200\"\n },\n \"last_error\": {\n \"code\": \"bird:business_not_registered\",\n \"description\": \"Apple refused the message with HTTP status 404.\"\n }\n }\n }\n },\n \"error\": \"connection refused\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "bdaf2a92-8960-86db-8cb3-d76c3fd5075b", "name": "Replay failed deliveries", "request": { "name": "Replay failed deliveries", "description": { "content": "Queues redelivery of deliveries that failed. The window runs from `since`\n(default: the last 24 hours) to `until`, and events the endpoint already received\nsuccessfully are skipped, so a replay never double-delivers.\n\nOnly failed attempts are replayed, and the window selects on attempt time rather than\non when the event occurred. An event the endpoint was never sent, such as one that\narrived while it was paused, has no failed attempt to replay, so a replay does not\nrecover it. Replay reads the delivery-attempt log, which retains three days, so that\nis the oldest history it reaches: an earlier `since` widens the window without\nrecovering anything older. A paused endpoint redelivers nothing at all:\nre-enable it with [Update a webhook endpoint](https://bird.com/docs/api/reference/update-webhook)\nfirst.\n\nThe `202` response means the replay is queued. Each redelivery then takes a single\nattempt rather than the retry schedule a live delivery follows, so a replay into an\nendpoint that is still broken costs one request per event; fix the endpoint and replay\nagain. No count or task ID is returned, so track results with\n[List delivery attempts](https://bird.com/docs/api/reference/list-webhook-attempts).\n\nOne replay redelivers at most the oldest 10,000 events in the window, and replays are\nlimited to 20 per organization per UTC day; beyond that the request returns a `429`\n`WebhookReplayQuotaExceeded`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "replay" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/replay" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"since\": \"2026-05-07T00:00:00Z\",\n \"until\": \"2026-05-07T23:59:59Z\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "a1857e7e-26af-8665-814a-d9ba131ae125", "name": "Replay queued. Events are redelivered asynchronously; no count or task ID is returned.", "originalRequest": { "name": "Replay failed deliveries", "description": { "content": "Queues redelivery of deliveries that failed. The window runs from `since`\n(default: the last 24 hours) to `until`, and events the endpoint already received\nsuccessfully are skipped, so a replay never double-delivers.\n\nOnly failed attempts are replayed, and the window selects on attempt time rather than\non when the event occurred. An event the endpoint was never sent, such as one that\narrived while it was paused, has no failed attempt to replay, so a replay does not\nrecover it. Replay reads the delivery-attempt log, which retains three days, so that\nis the oldest history it reaches: an earlier `since` widens the window without\nrecovering anything older. A paused endpoint redelivers nothing at all:\nre-enable it with [Update a webhook endpoint](https://bird.com/docs/api/reference/update-webhook)\nfirst.\n\nThe `202` response means the replay is queued. Each redelivery then takes a single\nattempt rather than the retry schedule a live delivery follows, so a replay into an\nendpoint that is still broken costs one request per event; fix the endpoint and replay\nagain. No count or task ID is returned, so track results with\n[List delivery attempts](https://bird.com/docs/api/reference/list-webhook-attempts).\n\nOne replay redelivers at most the oldest 10,000 events in the window, and replays are\nlimited to 20 per organization per UTC day; beyond that the request returns a `429`\n`WebhookReplayQuotaExceeded`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "replay" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/replay" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"since\": \"2026-05-07T00:00:00Z\",\n \"until\": \"2026-05-07T23:59:59Z\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "key": "Content-Type", "value": "text/plain" } ], "body": "", "cookie": [], "_postman_previewlanguage": "text" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "b1d84e7e-7e9d-8a9c-865b-b5601b2f4dca", "name": "List delivery attempts", "request": { "name": "List delivery attempts", "description": { "content": "Returns the endpoint's recent delivery attempts, newest first. Each entry is one HTTP\nrequest, so a retried event appears once per try; use it to see what failed and why\nbefore requesting redelivery with\n[Replay failed deliveries](https://bird.com/docs/api/reference/create-webhook-replay).\n\nBound the window with the `before`/`after` timestamps and cap the page with `limit`.\nTo page further back without a cursor, pass the oldest `attempted_at`\nyou received as `before`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "attempts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "50", "description": "Maximum number of attempts to return. Defaults to 50, capped at 100." }, { "disabled": true, "key": "before", "value": "", "description": "Only return attempts strictly before this timestamp." }, { "disabled": true, "key": "after", "value": "", "description": "Only return attempts strictly after this timestamp." } ], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/attempts?limit=50" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "f13b426c-f0d6-8126-803b-a5d5e5c94c29", "name": "Recent delivery attempts.", "originalRequest": { "name": "List delivery attempts", "description": { "content": "Returns the endpoint's recent delivery attempts, newest first. Each entry is one HTTP\nrequest, so a retried event appears once per try; use it to see what failed and why\nbefore requesting redelivery with\n[Replay failed deliveries](https://bird.com/docs/api/reference/create-webhook-replay).\n\nBound the window with the `before`/`after` timestamps and cap the page with `limit`.\nTo page further back without a cursor, pass the oldest `attempted_at`\nyou received as `before`.\n", "type": "text/plain" }, "url": { "path": [ "v1", "webhooks", ":webhook_id", "attempts" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": false, "key": "limit", "value": "50", "description": "Maximum number of attempts to return. Defaults to 50, capped at 100." }, { "disabled": true, "key": "before", "value": "", "description": "Only return attempts strictly before this timestamp." }, { "disabled": true, "key": "after", "value": "", "description": "Only return attempts strictly after this timestamp." } ], "variable": [ { "disabled": false, "type": "any", "value": "whk_01krdgeqcxet5s7t44vh8rt9mg", "key": "webhook_id", "description": "(Required) ID of the webhook endpoint (`whk_` prefix), as returned when it was created." } ], "raw": "{{BIRD_API_URL}}/v1/webhooks/:webhook_id/attempts?limit=50" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"msgatt_3FdaB1NkOmM6m8AxhgEYTJgqHU3\",\n \"event_id\": \"whe_01krdgeqcxet5s7t44vh8rt9mg\",\n \"event_type\": \"amb.accepted\",\n \"status\": \"delivered\",\n \"url\": \"https://example.com/webhooks\",\n \"failure_reason\": \"The endpoint's connection changed after this delivery was queued.\",\n \"response_status_code\": 200,\n \"response_body\": \"{\\\"ok\\\":true}\",\n \"response_duration_ms\": 87,\n \"attempted_at\": \"2026-05-22T11:50:38.080Z\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "8b806e60-292e-8394-8432-a0b463a9b4e4", "name": "voice-legs", "description": { "content": "Call records (CDR) for the workspace, in flight and completed.", "type": "text/plain" }, "item": [ { "id": "761e1565-131f-8ff0-83eb-7baaa2c93906", "name": "List legs", "request": { "name": "List legs", "description": { "content": "Returns a paginated list of the workspace's legs, ordered by start time\ndescending.\n\nThe `status` filter selects where in the lifecycle you look, and any\ncombination is a single page: in-flight statuses (`ringing`,\n`in_progress`), final ones, or both together. Omit it and you get\ncompleted legs, which is what this list has always returned.\n\nA leg in flight carries no economics yet: `duration_ms`, `billable_ms`,\n`ended_at`, and `cost` are null until it ends. It keeps the same `id`\nthroughout, so the same leg answers under one identity from the first\nring to settlement.\n", "type": "text/plain" }, "url": { "path": [ "v1", "voice", "legs" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "direction", "value": "", "description": "Return only legs in this direction." }, { "disabled": true, "key": "status", "value": "", "description": "Return only legs with one of these statuses, comma-separated.\nIn-flight and final statuses may be combined freely.\n" }, { "disabled": true, "key": "call_id", "value": "", "description": "Return only legs belonging to this call, which is how the legs of one multi-party or transferred call are correlated." }, { "disabled": true, "key": "sip_trunk_id", "value": "", "description": "Return only legs carried by this SIP trunk." }, { "disabled": false, "key": "from", "value": "+14155551234", "description": "Return only legs placed from this calling party number, matched as a whole number rather than as a fragment. Give it in international form: `+14155551234`, `14155551234`, and `0014155551234` all select the same legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. Use `number` instead to match part of a number, or either side of the leg.\n" }, { "disabled": false, "key": "to", "value": "+16505559876", "description": "Return only legs placed to this called party number, matched as a whole number rather than as a fragment. Give it in international form: `+16505559876`, `16505559876`, and `0016505559876` all select the same legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. Use `number` instead to match part of a number, or either side of the leg.\n" }, { "disabled": true, "key": "number", "value": "", "description": "Return only legs where the calling or called number contains this value. Matches a partial number, so a country or area-code prefix returns every leg to or from it. Combines with `from`/`to`, which match one side exactly." }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "started_after", "value": "", "description": "Return only legs that started at or after this instant, inclusive. RFC 3339 timestamp." }, { "disabled": true, "key": "started_before", "value": "", "description": "Return only legs that started at or before this instant, inclusive. RFC 3339 timestamp." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/voice/legs?from=+14155551234&to=+16505559876&limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "422d1426-9d93-8bc8-892c-4a46d3a29ff9", "name": "Paginated list of leg records.", "originalRequest": { "name": "List legs", "description": { "content": "Returns a paginated list of the workspace's legs, ordered by start time\ndescending.\n\nThe `status` filter selects where in the lifecycle you look, and any\ncombination is a single page: in-flight statuses (`ringing`,\n`in_progress`), final ones, or both together. Omit it and you get\ncompleted legs, which is what this list has always returned.\n\nA leg in flight carries no economics yet: `duration_ms`, `billable_ms`,\n`ended_at`, and `cost` are null until it ends. It keeps the same `id`\nthroughout, so the same leg answers under one identity from the first\nring to settlement.\n", "type": "text/plain" }, "url": { "path": [ "v1", "voice", "legs" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "direction", "value": "", "description": "Return only legs in this direction." }, { "disabled": true, "key": "status", "value": "", "description": "Return only legs with one of these statuses, comma-separated.\nIn-flight and final statuses may be combined freely.\n" }, { "disabled": true, "key": "call_id", "value": "", "description": "Return only legs belonging to this call, which is how the legs of one multi-party or transferred call are correlated." }, { "disabled": true, "key": "sip_trunk_id", "value": "", "description": "Return only legs carried by this SIP trunk." }, { "disabled": false, "key": "from", "value": "+14155551234", "description": "Return only legs placed from this calling party number, matched as a whole number rather than as a fragment. Give it in international form: `+14155551234`, `14155551234`, and `0014155551234` all select the same legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. Use `number` instead to match part of a number, or either side of the leg.\n" }, { "disabled": false, "key": "to", "value": "+16505559876", "description": "Return only legs placed to this called party number, matched as a whole number rather than as a fragment. Give it in international form: `+16505559876`, `16505559876`, and `0016505559876` all select the same legs. A number given without a country code is read as an international one, so give the country code to be sure of what you are matching. Use `number` instead to match part of a number, or either side of the leg.\n" }, { "disabled": true, "key": "number", "value": "", "description": "Return only legs where the calling or called number contains this value. Matches a partial number, so a country or area-code prefix returns every leg to or from it. Combines with `from`/`to`, which match one side exactly." }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "tag", "value": "", "description": "Filter by tag. Accepts `name` to match any record carrying that tag name, or `name:value` to match a specific tag pair (for example `category:welcome`). Repeat the parameter to add more tags. A record must match every tag listed to be returned.\n" }, { "disabled": true, "key": "started_after", "value": "", "description": "Return only legs that started at or after this instant, inclusive. RFC 3339 timestamp." }, { "disabled": true, "key": "started_before", "value": "", "description": "Return only legs that started at or before this instant, inclusive. RFC 3339 timestamp." }, { "disabled": false, "key": "limit", "value": "25", "description": "Maximum number of items to return per page." }, { "disabled": true, "key": "starting_after", "value": "", "description": "Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order." }, { "disabled": true, "key": "ending_before", "value": "", "description": "Cursor from the `prev_cursor` or `refresh_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order. `prev_cursor` returns the preceding page. `refresh_cursor` anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since." } ], "variable": [], "raw": "{{BIRD_API_URL}}/v1/voice/legs?from=+14155551234&to=+16505559876&limit=25" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"id\": \"vcl_01krdgeqcxet5s7t44vh8rt9mg\",\n \"call_id\": \"vcs_01krdgeqcxet5s7t44vh8rt9mg\",\n \"workspace_id\": \"ws_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"from\": \"+14155551234\",\n \"to\": \"+16505559876\",\n \"actor\": {\n \"id\": \"usr_01krdgeqcxet5s7t44vh8rt9mg\",\n \"type\": \"user\"\n },\n \"sip_trunk_id\": \"spt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"sip_call_id\": \"3f9a1c8e7b2d4a5f@sip.example.net\",\n \"status\": \"answered\",\n \"sip_response_code\": 200,\n \"rejection_reason\": \"destination_not_enabled\",\n \"route\": {\n \"type\": \"trunk\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"duration_ms\": 65000,\n \"pdd_ms\": 850,\n \"billable_ms\": 60000,\n \"media_quality\": {\n \"mos\": 4.32,\n \"jitter_ms\": 12,\n \"packet_loss_pct\": 1.5,\n \"round_trip_time_ms\": 42\n },\n \"cost\": {\n \"amount\": \"0.013000\",\n \"currency_code\": \"USD\",\n \"outbound_amount\": \"0.013000\",\n \"inbound_amount\": null,\n \"call_handling_amount\": null,\n \"recording_amount\": null,\n \"transcription_amount\": null\n }\n }\n ],\n \"next_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9\",\n \"prev_cursor\": null,\n \"refresh_cursor\": \"eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "bb2b8ed1-728c-8ce2-801e-84c6a58ada73", "name": "Get a leg", "request": { "name": "Get a leg", "description": { "content": "Returns a single leg at any point in its lifecycle. A leg that is still ringing or connected answers with its in-flight `status` and no economics: `duration_ms`, `billable_ms`, and `ended_at` fill in once it ends, at this same URL, and `cost` does too unless the leg was never rated, as with a verification call Bird places and answers on your behalf. Returns a 404 `not_found_error` if the leg does not exist in the workspace.\n", "type": "text/plain" }, "url": { "path": [ "v1", "voice", "legs", ":leg_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "vcl_01k0p3v9wera3v6q6xw3e9y2mh", "key": "leg_id", "description": "(Required) " } ], "raw": "{{BIRD_API_URL}}/v1/voice/legs/:leg_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "e298bb22-6fb2-8e28-8de3-ef1e06946117", "name": "The leg's current status, timing, and routing details.", "originalRequest": { "name": "Get a leg", "description": { "content": "Returns a single leg at any point in its lifecycle. A leg that is still ringing or connected answers with its in-flight `status` and no economics: `duration_ms`, `billable_ms`, and `ended_at` fill in once it ends, at this same URL, and `cost` does too unless the leg was never rated, as with a verification call Bird places and answers on your behalf. Returns a 404 `not_found_error` if the leg does not exist in the workspace.\n", "type": "text/plain" }, "url": { "path": [ "v1", "voice", "legs", ":leg_id" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "vcl_01k0p3v9wera3v6q6xw3e9y2mh", "key": "leg_id", "description": "(Required) " } ], "raw": "{{BIRD_API_URL}}/v1/voice/legs/:leg_id" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"vcl_01krdgeqcxet5s7t44vh8rt9mg\",\n \"call_id\": \"vcs_01krdgeqcxet5s7t44vh8rt9mg\",\n \"workspace_id\": \"ws_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"from\": \"+14155551234\",\n \"to\": \"+16505559876\",\n \"actor\": {\n \"id\": \"usr_01krdgeqcxet5s7t44vh8rt9mg\",\n \"type\": \"user\"\n },\n \"sip_trunk_id\": \"spt_01krdgeqcxet5s7t44vh8rt9mg\",\n \"sip_call_id\": \"3f9a1c8e7b2d4a5f@sip.example.net\",\n \"status\": \"answered\",\n \"sip_response_code\": 200,\n \"rejection_reason\": \"destination_not_enabled\",\n \"route\": {\n \"type\": \"trunk\"\n },\n \"tags\": [\n {\n \"name\": \"category\",\n \"value\": \"welcome\"\n }\n ],\n \"duration_ms\": 65000,\n \"pdd_ms\": 850,\n \"billable_ms\": 60000,\n \"media_quality\": {\n \"mos\": 4.32,\n \"jitter_ms\": 12,\n \"packet_loss_pct\": 1.5,\n \"round_trip_time_ms\": 42\n },\n \"cost\": {\n \"amount\": \"0.013000\",\n \"currency_code\": \"USD\",\n \"outbound_amount\": \"0.013000\",\n \"inbound_amount\": null,\n \"call_handling_amount\": null,\n \"recording_amount\": null,\n \"transcription_amount\": null\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "67284b26-d03b-8be2-8d40-b0a11247f2e5", "name": "lookup", "description": { "content": "Inspect a recipient before sending. Phone-number lookups return carrier, portability, number type, reachability, roaming, SIM-change, and fraud-risk data when requested. Email lookups return deliverability, confidence, failure reasons, and suggested corrections for likely misspellings.\n", "type": "text/plain" }, "item": [ { "id": "9ae267b1-d749-809b-8999-831ef6d50baf", "name": "Create a phone number lookup", "request": { "name": "Create a phone number lookup", "description": { "content": "Returns the number's serving and issuing networks, porting state, country, and line type. The baseline fields are included in each lookup. Request additional `type` blocks for classification, presence, roaming, SIM-swap, porting-history, or credibility data. Each block reports its own `status`; only blocks with an `ok` status incur an additional charge.\n\nThis form keeps the number out of the URL. The [URL form](https://bird.com/docs/api/reference/get-phone-number-lookup) performs the same lookup but cannot use an idempotency key. With this form, reuse an `Idempotency-Key` to return the stored result without another lookup or charge.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "phone-number" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/lookup/phone-number" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phone_number\": \"+31612345678\",\n \"type\": [\n \"classification\",\n \"presence\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "758bfe77-2235-8cef-8548-aeac450ef6fc", "name": "Available network and number-intelligence information.", "originalRequest": { "name": "Create a phone number lookup", "description": { "content": "Returns the number's serving and issuing networks, porting state, country, and line type. The baseline fields are included in each lookup. Request additional `type` blocks for classification, presence, roaming, SIM-swap, porting-history, or credibility data. Each block reports its own `status`; only blocks with an `ok` status incur an additional charge.\n\nThis form keeps the number out of the URL. The [URL form](https://bird.com/docs/api/reference/get-phone-number-lookup) performs the same lookup but cannot use an idempotency key. With this form, reuse an `Idempotency-Key` to return the stored result without another lookup or charge.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "phone-number" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/lookup/phone-number" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"phone_number\": \"+31612345678\",\n \"type\": [\n \"classification\",\n \"presence\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"phone_number\": \"+441904123456\",\n \"country_code\": \"GB\",\n \"network_info\": {\n \"carrier_name\": \"BT\",\n \"mcc\": \"234\",\n \"mnc\": \"00\"\n },\n \"original_network_info\": null,\n \"flags\": [],\n \"line_type\": \"service\",\n \"classification\": {\n \"status\": \"ok\",\n \"value\": \"premium_rate\"\n },\n \"score\": {\n \"status\": \"ok\",\n \"value\": 48\n },\n \"presence\": {\n \"status\": \"ok\",\n \"reachable\": true\n },\n \"roaming\": {\n \"status\": \"unavailable\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f7dd69a7-1755-8a6d-8def-4f4fa94710b3", "name": "Get a phone number lookup by URL", "request": { "name": "Get a phone number lookup by URL", "description": { "content": "Performs the same lookup as [Create a phone number lookup](https://bird.com/docs/api/reference/create-phone-number-lookup), with the number in the URL. The response includes the number's serving and issuing networks, porting state, country, and line type. Repeat `type` to request additional blocks, such as `?type=classification&type=score`; only blocks with an `ok` status incur an additional charge.\n\nBecause the number is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an `Idempotency-Key`; each retry performs and charges for another lookup.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "phone-number", ":number" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "type", "value": "", "description": "An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is `ok`." }, { "disabled": true, "key": "type", "value": "", "description": "An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is `ok`." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "number", "description": "(Required) The number to look up, in international format. The leading `+` is optional, and `00` works in its place, so `31612345678` and `+31612345678` are the same number, with nothing to percent-encode. If you do send the `+`, percent-encode it as `%2B` when your client does not do that for you." } ], "raw": "{{BIRD_API_URL}}/v1/lookup/phone-number/:number" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "47959de7-5924-8607-8443-a5c94cd5c430", "name": "Available network and number-intelligence information.", "originalRequest": { "name": "Get a phone number lookup by URL", "description": { "content": "Performs the same lookup as [Create a phone number lookup](https://bird.com/docs/api/reference/create-phone-number-lookup), with the number in the URL. The response includes the number's serving and issuing networks, porting state, country, and line type. Repeat `type` to request additional blocks, such as `?type=classification&type=score`; only blocks with an `ok` status incur an additional charge.\n\nBecause the number is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an `Idempotency-Key`; each retry performs and charges for another lookup.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "phone-number", ":number" ], "host": [ "{{BIRD_API_URL}}" ], "query": [ { "disabled": true, "key": "type", "value": "", "description": "An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is `ok`." }, { "disabled": true, "key": "type", "value": "", "description": "An additional data block to request. Repeat the parameter for multiple blocks; each block is billed separately only when its status is `ok`." } ], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "number", "description": "(Required) The number to look up, in international format. The leading `+` is optional, and `00` works in its place, so `31612345678` and `+31612345678` are the same number, with nothing to percent-encode. If you do send the `+`, percent-encode it as `%2B` when your client does not do that for you." } ], "raw": "{{BIRD_API_URL}}/v1/lookup/phone-number/:number" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"phone_number\": \"+441904123456\",\n \"country_code\": \"GB\",\n \"network_info\": {\n \"carrier_name\": \"BT\",\n \"mcc\": \"234\",\n \"mnc\": \"00\"\n },\n \"original_network_info\": null,\n \"flags\": [],\n \"line_type\": \"service\",\n \"classification\": {\n \"status\": \"ok\",\n \"value\": \"premium_rate\"\n },\n \"score\": {\n \"status\": \"ok\",\n \"value\": 48\n },\n \"presence\": {\n \"status\": \"ok\",\n \"reachable\": true\n },\n \"roaming\": {\n \"status\": \"unavailable\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "d96c5cfe-f67e-8766-8240-9ac12defd7aa", "name": "Create an email address lookup", "request": { "name": "Create an email address lookup", "description": { "content": "Returns a deliverability `result`, a `delivery_confidence` score, address characteristics, an assessment `reason`, and a suggested correction when available. `result` and `reason` are open vocabularies. Handle unknown values and use `delivery_confidence` as the stable fallback. Each completed lookup incurs the same charge regardless of its result.\n\nThis form keeps the address out of the URL. The [URL form](https://bird.com/docs/api/reference/get-email-lookup) performs the same lookup but cannot use an idempotency key. With this form, reuse an `Idempotency-Key` to return the stored result without another lookup or charge.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "email" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/lookup/email" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"email\": \"aisha.khan@example.com\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "b95b6aa9-f725-89b4-85d2-b066ca4473d6", "name": "Available deliverability information about the address.", "originalRequest": { "name": "Create an email address lookup", "description": { "content": "Returns a deliverability `result`, a `delivery_confidence` score, address characteristics, an assessment `reason`, and a suggested correction when available. `result` and `reason` are open vocabularies. Handle unknown values and use `delivery_confidence` as the stable fallback. Each completed lookup incurs the same charge regardless of its result.\n\nThis form keeps the address out of the URL. The [URL form](https://bird.com/docs/api/reference/get-email-lookup) performs the same lookup but cannot use an idempotency key. With this form, reuse an `Idempotency-Key` to return the stored result without another lookup or charge.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "email" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/lookup/email" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"email\": \"aisha.khan@example.com\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"email\": \"aisha.khan@example.com\",\n \"valid\": true,\n \"result\": \"risky\",\n \"delivery_confidence\": 42,\n \"flags\": [\n \"role\",\n \"free_provider\"\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "91d5657e-6b2c-81a2-8e81-8b09d105c151", "name": "Create a batch of email address lookups", "request": { "name": "Create a batch of email address lookups", "description": { "content": "Assesses up to 1,000 email addresses synchronously and returns one result per\ninput in submission order. Malformed addresses receive individual assessments.\nDuplicate addresses remain separate entries and each answered entry is billed\nat the email lookup rate. Use [Create an email address lookup](https://bird.com/docs/api/reference/create-email-lookup)\nfor a single address. A batch consumes one request allowance under the shared\nlookup rate limit, regardless of its number of addresses.\n\nRequests must fit within 128 KiB. Split larger lists into separate requests.\nReuse an `Idempotency-Key` for retries of the same batch. Successful responses\nup to 256 KiB can be retained for replay; larger responses are returned but\nare not retained, so retrying can perform and charge for another batch.\nAn unavailable lookup returns `503` without charging for the batch.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "email", "batch" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/lookup/email/batch" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"emails\": [\n \"aisha.khan@example.com\",\n \"not-an-email\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "924df7bb-cab3-8e45-8dbf-d64824c39b03", "name": "Completed assessments in submission order.", "originalRequest": { "name": "Create a batch of email address lookups", "description": { "content": "Assesses up to 1,000 email addresses synchronously and returns one result per\ninput in submission order. Malformed addresses receive individual assessments.\nDuplicate addresses remain separate entries and each answered entry is billed\nat the email lookup rate. Use [Create an email address lookup](https://bird.com/docs/api/reference/create-email-lookup)\nfor a single address. A batch consumes one request allowance under the shared\nlookup rate limit, regardless of its number of addresses.\n\nRequests must fit within 128 KiB. Split larger lists into separate requests.\nReuse an `Idempotency-Key` for retries of the same batch. Successful responses\nup to 256 KiB can be retained for replay; larger responses are returned but\nare not retained, so retrying can perform and charge for another batch.\nAn unavailable lookup returns `503` without charging for the batch.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "email", "batch" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/lookup/email/batch" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"emails\": [\n \"aisha.khan@example.com\",\n \"not-an-email\"\n ]\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"data\": [\n {\n \"email\": \"aisha.khan@example.com\",\n \"valid\": true,\n \"result\": \"risky\",\n \"delivery_confidence\": 42,\n \"flags\": [\n \"role\",\n \"free_provider\"\n ]\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "7fb7fece-3678-8acd-8f31-f1e512582e31", "name": "Get an email address lookup by URL", "request": { "name": "Get an email address lookup by URL", "description": { "content": "Performs the same deliverability lookup as [Create an email address lookup](https://bird.com/docs/api/reference/create-email-lookup), with the address in the URL. The response includes a result, confidence score, address characteristics, assessment reason, and suggested correction when available. Treat unknown `result` and `reason` values as valid additions.\n\nBecause the address is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an `Idempotency-Key`; each retry performs and charges for another lookup.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "email", ":address" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "address", "description": "(Required) The email address to look up. Percent-encode it, because a local part may legally contain characters a URL path reads as structure. The `@` itself is safe either way." } ], "raw": "{{BIRD_API_URL}}/v1/lookup/email/:address" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "response": [ { "id": "cedaed78-fc79-8aad-8407-af8044a05d0e", "name": "Available deliverability information about the address.", "originalRequest": { "name": "Get an email address lookup by URL", "description": { "content": "Performs the same deliverability lookup as [Create an email address lookup](https://bird.com/docs/api/reference/create-email-lookup), with the address in the URL. The response includes a result, confidence score, address characteristics, assessment reason, and suggested correction when available. Treat unknown `result` and `reason` values as valid additions.\n\nBecause the address is in the URL, it can appear in proxies, access logs, and browser history. This form does not accept an `Idempotency-Key`; each retry performs and charges for another lookup.\n", "type": "text/plain" }, "url": { "path": [ "v1", "lookup", "email", ":address" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [ { "disabled": false, "type": "any", "value": "", "key": "address", "description": "(Required) The email address to look up. Percent-encode it, because a local part may legally contain characters a URL path reads as structure. The `@` itself is safe either way." } ], "raw": "{{BIRD_API_URL}}/v1/lookup/email/:address" }, "header": [ { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Accept", "value": "", "disabled": true } ], "method": "GET" }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"email\": \"aisha.khan@example.com\",\n \"valid\": true,\n \"result\": \"risky\",\n \"delivery_confidence\": 42,\n \"flags\": [\n \"role\",\n \"free_provider\"\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "c4b80b69-3fe2-8a16-8162-3795c34e6e63", "name": "voice-calls", "description": { "content": "One navigational entry per call and every leg that belongs to it, with whether it produced a recording or a transcript.", "type": "text/plain" }, "item": [ { "id": "324d78bb-d709-8458-8a82-053783a06701", "name": "Create a call", "request": { "name": "Create a call", "description": { "content": "Accepts a real outbound call that runs a voice sequence after the\nrecipient answers, starting at the selected entry node. Supply exactly one\nof `sequence.id`, to run the active publication of a saved sequence, or\n`sequence.definition`, to run a complete definition once without saving\nit. Production availability rules and normal calling charges apply.\nRequires both voice management write and voice calling write permissions\nand a permitted calling number. Browser users and API keys are supported.\nDraft and test selectors are not accepted. See the\n[Create Call guide](https://bird.com/docs/guides/voice/create-calls).\n\nAn inline definition must pass the same checks as publishing a sequence;\nthe first blocking problem returns 422 with its location under\n`/sequence/definition`. Its run executes at most 16 commands, including\ngather prompts; a call that needs a 17th ends with the `call_limit`\ntrace error instead of running it. The accepted call's\n`sequence.id` is `null`, because its run belongs to no saved sequence.\n\nSupply sequence trigger data as an explicit object matching the selected\nentry's configured data schema, or an empty object when no data is needed.\nThe active publication or inline definition, entry node, and trigger data\nare frozen when the call is accepted. The response contains reserved call and initial-leg IDs.\nIts `null` `started_at`, `false` `live`, and empty `parties` describe the\nacceptance snapshot. Acceptance does not guarantee that dialing starts or\nthat call and leg reads become available. A call that fails or is canceled\nbefore registration might never appear in those reads. Read progress\nin the sequence's Runs tab in the dashboard. Once the initial leg is\nregistered, use its `initial_leg_id` with `GET /v1/voice/legs/{leg_id}` to\ninspect the telephone outcome; that read requires voice read permission.\n\nIdempotency is optional. Without an `Idempotency-Key` header, each request\naccepts a new call attempt. To protect retries, supply a key on the first\nattempt and reuse it for the same intended call.\nRequests are limited to 128 KiB. The same idempotency key and exact request\nbytes replay the original acceptance snapshot for three hours. Changed\nrequests return 409. Authorization and calling-number permission are\nchecked on every request, including replays. Replays include the\nIdempotency-Replay header with value true.\n", "type": "text/plain" }, "url": { "path": [ "v1", "voice", "calls" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/voice/calls" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": \"+12025550100\",\n \"to\": \"+12025550101\",\n \"sequence\": {\n \"id\": \"vsq_01krdgeqcxet5s7t44vh8rt9mg\",\n \"entry_node_id\": \"start\",\n \"trigger_data\": {}\n }\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "551c4910-9037-881d-8695-b739b04ff634", "name": "Immutable acceptance snapshot for the call.", "originalRequest": { "name": "Create a call", "description": { "content": "Accepts a real outbound call that runs a voice sequence after the\nrecipient answers, starting at the selected entry node. Supply exactly one\nof `sequence.id`, to run the active publication of a saved sequence, or\n`sequence.definition`, to run a complete definition once without saving\nit. Production availability rules and normal calling charges apply.\nRequires both voice management write and voice calling write permissions\nand a permitted calling number. Browser users and API keys are supported.\nDraft and test selectors are not accepted. See the\n[Create Call guide](https://bird.com/docs/guides/voice/create-calls).\n\nAn inline definition must pass the same checks as publishing a sequence;\nthe first blocking problem returns 422 with its location under\n`/sequence/definition`. Its run executes at most 16 commands, including\ngather prompts; a call that needs a 17th ends with the `call_limit`\ntrace error instead of running it. The accepted call's\n`sequence.id` is `null`, because its run belongs to no saved sequence.\n\nSupply sequence trigger data as an explicit object matching the selected\nentry's configured data schema, or an empty object when no data is needed.\nThe active publication or inline definition, entry node, and trigger data\nare frozen when the call is accepted. The response contains reserved call and initial-leg IDs.\nIts `null` `started_at`, `false` `live`, and empty `parties` describe the\nacceptance snapshot. Acceptance does not guarantee that dialing starts or\nthat call and leg reads become available. A call that fails or is canceled\nbefore registration might never appear in those reads. Read progress\nin the sequence's Runs tab in the dashboard. Once the initial leg is\nregistered, use its `initial_leg_id` with `GET /v1/voice/legs/{leg_id}` to\ninspect the telephone outcome; that read requires voice read permission.\n\nIdempotency is optional. Without an `Idempotency-Key` header, each request\naccepts a new call attempt. To protect retries, supply a key on the first\nattempt and reuse it for the same intended call.\nRequests are limited to 128 KiB. The same idempotency key and exact request\nbytes replay the original acceptance snapshot for three hours. Changed\nrequests return 409. Authorization and calling-number permission are\nchecked on every request, including replays. Replays include the\nIdempotency-Replay header with value true.\n", "type": "text/plain" }, "url": { "path": [ "v1", "voice", "calls" ], "host": [ "{{BIRD_API_URL}}" ], "query": [], "variable": [], "raw": "{{BIRD_API_URL}}/v1/voice/calls" }, "header": [ { "disabled": true, "description": "Client-supplied key. On operations supporting request deduplication, a retained\nresponse is replayed for duplicate requests with the same key within the\nidempotency window (3 hours by default). This protection requires a workspace,\norganization, or staff-account scope. User-only and unscoped unauthenticated operations,\nstreams, and operations with a separate replay contract do not use this\nresponse replay.\n\nOn a supported operation, if idempotency protection is unavailable before execution, the API returns\n`503 IdempotencyUnavailable` (E01033) without executing this attempt. Retry with\nbackoff using the same key and request. An operation that takes effect before\nits response is retained can still execute again on retry.\n\nTwo distinct 409 errors signal misuse:\n\n- `request_in_progress` (E01004): The same key is currently being\n processed by a concurrent request. Wait briefly and retry. The lock expires within 30 seconds.\n- `idempotency_key_reuse` (E01005): The same key has already completed\n against a different request body or method. Generate a new key.\n\nRecommended key format is `/` (for example `welcome-user/usr_abc123`).\n", "key": "Idempotency-Key", "value": "" }, { "disabled": true, "description": "Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.", "key": "X-Workspace-Id", "value": "" }, { "disabled": true, "description": "Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.", "key": "X-Organization-Id", "value": "" }, { "key": "Content-Type", "value": "", "disabled": true }, { "key": "Accept", "value": "", "disabled": true } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"from\": \"+12025550100\",\n \"to\": \"+12025550101\",\n \"sequence\": {\n \"id\": \"vsq_01krdgeqcxet5s7t44vh8rt9mg\",\n \"entry_node_id\": \"start\",\n \"trigger_data\": {}\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "Accepted", "code": 202, "header": [ { "disabled": false, "description": "The API includes this header when it replays the response for an earlier request that used the same `Idempotency-Key`. The API does not process the request again.", "key": "Idempotency-Replay", "value": "" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"id\": \"vcs_01krdgeqcxet5s7t44vh8rt9mg\",\n \"workspace_id\": \"ws_01krdgeqcxet5s7t44vh8rt9mg\",\n \"initial_leg_id\": \"vcl_01krdgeqcxet5s7t44vh8rt9mg\",\n \"direction\": \"outbound\",\n \"started_at\": null,\n \"ended_at\": null,\n \"live\": false,\n \"has_recording\": false,\n \"has_transcript\": false,\n \"parties\": [],\n \"sequence\": {\n \"id\": \"vsq_01krdgeqcxet5s7t44vh8rt9mg\",\n \"run_id\": \"vsr_01krdgeqcxet5s7t44vh8rt9mg\"\n }\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] } ], "event": [], "variable": [ { "key": "BIRD_API_URL", "value": "https://us1.platform.bird.com" }, { "key": "BIRD_API_KEY", "value": "" } ], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{BIRD_API_KEY}}" } ] }, "info": { "_postman_id": "742faa70-15ff-8695-81e6-960014194f34", "name": "Bird API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "Build communications into your applications and AI workflows with the Bird API.\nExplore endpoints for email, SMS, WhatsApp, verification, and realtime messaging.\n\nStart with the [developer documentation](https://bird.com/docs), browse the\n[API reference](https://bird.com/docs/api), or connect your agent through the\n[Bird MCP server](https://bird.com/docs/ai/mcp-server).\n\nSetting a `User-Agent` header is recommended but not required. Official Bird\nSDKs set it automatically (format: `bird-/`). The header is\nused for operational logging and customer-support diagnostics; the API never\nrejects requests that omit it.\n\nRate limits are advertised on every response from a rate-limited endpoint as\nIETF `RateLimit` and `RateLimit-Policy` headers (Structured Fields per RFC\n9651; spec draft-ietf-httpapi-ratelimit-headers-11). On 429 responses, a\n`Retry-After` header in seconds is also returned. Clients should pace\nthemselves against the `r` (remaining) and `t` (seconds until reset) params\nin the `RateLimit` header rather than only reacting to 429s.\n\n", "type": "text/plain" } } }