---
title: "List SMS messaging profiles"
canonical: "https://bird.com/docs/api/reference/list-sms-messaging-profiles"
---

# List SMS messaging profiles

`GET /v1/sms/messaging-profiles`

Returns your workspace's messaging profiles, newest first. A profile holds the senders, reply numbers, and sending defaults for one program.

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.
- `https://platform.bird.com`: Region-independent endpoint for authentication and account administration.
- `http://localhost:8080`: Local development.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

- `CookieAuth`: Send `bird_session` in cookie. Session cookie set after signing in to the Bird dashboard. The cookie
value is an opaque session token; no session data is stored in the cookie
itself.

## Code samples

**CLI**

```sh
bird sms messaging-profiles list
```

Examples: [CLI](/docs/api/reference/list-sms-messaging-profiles.cli.md) · [MCP](/docs/api/reference/list-sms-messaging-profiles.mcp.md) · [cURL](/docs/api/reference/list-sms-messaging-profiles.curl.md)

## Example response `200`

```json
{
  "data": [
    {
      "id": "mpr_01krdgeqcxet5s7t44vh8rt9mg",
      "name": "device-activation",
      "senders": [
        {
          "country_code": "US",
          "sender_id": "snd_01krdgeqcxet5s7t44vh8rt9mg"
        }
      ],
      "inbound": {
        "numbers": [
          {
            "country_code": "US",
            "number": "34001"
          }
        ],
        "callback_url": "https://receipts.example.com/bird/sms/inbound",
        "outbound_matching": {
          "enabled": false,
          "time_window": "1d"
        }
      },
      "default_category": "authentication",
      "validity_period": 3600,
      "cost_center": "CC001234",
      "options": {
        "smart_encoding": false,
        "ignore_suppression": false,
        "callback_url": "https://receipts.example.com/bird/sms/activation"
      },
      "callback_events": [
        "sms.delivered",
        "sms.failed"
      ]
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}
```

## Query parameters

- `sort` (string, optional)

  Field to sort by.

  Possible values: `created_at`
- `order` (string, optional)

  Sort direction. Defaults to `desc`, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

  Possible values: `asc`, `desc`
- `limit` (integer, optional): Maximum number of items to return per page.
- `starting_after` (string, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string, optional): 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.
- `include_total` (boolean, optional): When true, the response includes a `total` field with the total number of items matching the request's filters across all pages.

## Header parameters

- `X-Workspace-Id` (string, optional): 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.
- `X-Organization-Id` (string, optional): 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.

## Response body

- `data` (array of object, required): Your workspace's messaging profiles, newest first.
- `data.id` (string, required): Identifier of this profile.
- `data.name` (string, required): A label for the profile. Names are not unique, so two profiles can share one.
- `data.senders` (array of object, required): The sender for each destination country, and the default sender when an entry has no `country_code`.
- `data.senders.country_code` (string): The destination country this sender is used for, as an uppercase ISO 3166-1 alpha-2 code. Omit it to make this the default sender, which is used for every destination country that has no entry of its own. A profile can have one entry per country and one default. An empty string is rejected rather than treated as the default.
- `data.senders.sender_id` (string, required): The sender to use, as returned by the list SMS senders operation.
- `data.inbound` (object, required): How the profile receives replies. A profile without numbers only sends.
- `data.inbound.numbers` (array of object, required): The numbers that receive replies for this profile.
- `data.inbound.numbers.country_code` (string): The country of a short code, as an uppercase ISO 3166-1 alpha-2 code. Required for a short code. Omit it for a number in E.164 format, which receives replies from subscribers in any country.
- `data.inbound.numbers.number` (string, required): A short code as digits, or a number in E.164 format. It must be a number your workspace holds that can receive SMS, and it can belong to one profile at a time.
- `data.inbound.callback_url` (nullable string, required): The HTTPS URL that receives `sms.received` events for replies on this profile's numbers, signed with your workspace callback signing secret. Null when none is set, in which case replies use `options.callback_url`, then your webhook subscriptions. While a URL applies, a reply skips your plain webhook endpoints.
- `data.inbound.outbound_matching` (object, required): Settings for pairing each reply with the message it answers, reported as the reply's `in_reply_to_message`. Bird pairs only messages sent from one of this profile's reply numbers while matching is on. Turning it off stops pairing, and turning it back on resumes it for messages still inside their window.
- `data.inbound.outbound_matching.enabled` (boolean, required): Whether replies are paired with the messages they answer.
- `data.inbound.outbound_matching.time_window` (string, required)

  How long after a message is sent a reply can still be paired with it: one hour (`1h`), 24 hours (`1d`), or 168 hours (`7d`). `1d` is the default.

  Possible values: `1h`, `1d`, `7d`
- `data.default_category` (nullable string, required): The category a free-text send that names this profile uses when it sets none: `transactional`, `marketing`, `authentication`, or `service`. A template send takes the template's category. Null when none is set.
- `data.validity_period` (nullable integer, required): How many seconds a message stays valid before it expires undelivered. Null when none is set. A send that omits `validity_period` uses it.
- `data.cost_center` (nullable string, required): A label for assigning the cost of this profile's messages. Null when none is set. A send that omits `cost_center` uses it.
- `data.options` (object, required): Sending options that messages from this profile use when a message does not set its own.
- `data.options.smart_encoding` (boolean, required): Whether text is converted to the GSM-7 character set where possible, to fit more characters in a segment.
- `data.options.ignore_suppression` (boolean, required): Whether messages are sent even if the recipient is suppressed for the sender, including after replying STOP. Messages that do not set `ignore_suppression` use this value. Only `authentication` and `transactional` messages can skip suppressions. It cannot be `true` while `default_category` is `marketing` or `service`. Bird must enable it for your workspace; until then, messages that use it are refused.
- `data.options.callback_url` (nullable string, required): The HTTPS URL that receives this profile's message events instead of your webhook endpoints. Null when none is set. Messages that do not set `callback_url` use it, and so do replies on the profile's numbers that have no `inbound.callback_url`. Each event is a signed POST, signed with your workspace callback signing secret, which `rotateWebhookCallbackSigningSecret` creates and returns once. While a URL applies, a message's events skip your plain webhook endpoints. MCP Events subscriptions and connector endpoints still receive them.
- `data.callback_events` (nullable array, required): The events of this profile's outbound messages that go to a callback URL: `sms.accepted`, `sms.sent`, `sms.delivered`, `sms.undelivered`, `sms.failed`, `sms.rejected`, and `sms.expired`. The list is fixed when a message is accepted, and applies only while the message has a callback URL: an event outside it then reaches neither the URL nor a plain webhook endpoint. Without a callback URL the list has no effect, and every event goes to your webhook endpoints. `sms.received` is never filtered. Null means every outbound event goes to the URL.
- `data.created_at` (string, required): When the profile was created.
- `data.updated_at` (string, required): When the profile was last changed.
- `next_cursor` (nullable string, required): Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.
- `prev_cursor` (nullable string, required): Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.
- `refresh_cursor` (nullable string, required): Refresh anchor, the first row of this response. Pass back as `ending_before` to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.
- `total` (nullable integer): Total number of items matching the request's filters across all pages. Present only when `include_total=true` was passed, and omitted otherwise.

## Related resources

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)