---
title: "Get an SMS messaging profile"
canonical: "https://bird.com/docs/api/reference/get-sms-messaging-profile"
---

# Get an SMS messaging profile

`GET /v1/sms/messaging-profiles/{profile_id}`

Returns one messaging profile, including its senders, reply numbers, and sending defaults.

## 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 get <profile-id>
```

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

## Example response `200`

```json
{
  "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"
  ]
}
```

## Path parameters

- `profile_id` (string, required): ID of the messaging profile, as returned when you created or listed profiles.

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

- `id` (string, required): Identifier of this profile.
- `name` (string, required): A label for the profile. Names are not unique, so two profiles can share one.
- `senders` (array of object, required): The sender for each destination country, and the default sender when an entry has no `country_code`.
- `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.
- `senders.sender_id` (string, required): The sender to use, as returned by the list SMS senders operation.
- `inbound` (object, required): How the profile receives replies. A profile without numbers only sends.
- `inbound.numbers` (array of object, required): The numbers that receive replies for this profile.
- `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.
- `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.
- `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.
- `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.
- `inbound.outbound_matching.enabled` (boolean, required): Whether replies are paired with the messages they answer.
- `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`
- `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.
- `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.
- `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.
- `options` (object, required): Sending options that messages from this profile use when a message does not set its own.
- `options.smart_encoding` (boolean, required): Whether text is converted to the GSM-7 character set where possible, to fit more characters in a segment.
- `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.
- `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.
- `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.
- `created_at` (string, required): When the profile was created.
- `updated_at` (string, required): When the profile was last changed.

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