# SMS Geo Permissions

This guide shows you how to use **SMS Geo Permissions** to reduce your exposure to SMS-based fraud and related unexpected financial risks.

* Learn [what SMS Geo Permissions are](#purpose-of-sms-geo-permissions) and why setting them appropriately is critical
* Follow the [step-by-step guide on how to change SMS Geo Permissions](#how-to-change-sms-geo-permissions)
* Understand how to work with [SMS Geo Permission when using Subaccounts or Twilio Organizations](#permissions-inheritance-with-subaccounts-and-organizations)
* Find out how to [audit SMS Geo Permission changes](#auditing-sms-geo-permission-changes)

## Purpose of SMS Geo Permissions

Twilio supports sending SMS messages to [many countries globally](https://www.twilio.com/en-us/guidelines/sms). While this capability provides you with a wide reach to serve your use cases, it is just as important to use the tools available to you to manage your exposure to risks such as [SMS Pumping Fraud](/docs/messaging/guides/preventing-messaging-fraud).

SMS Geo Permissions are one such tool. Configuring SMS Geo Permissions allows you to control the list of countries to which you can send SMS messages. Given the rise of fraud in the SMS ecosystem, Twilio recommends disabling destination countries your business doesn't use or uses infrequently as a line of defense against fraudulent activity.

By default a newly created account allows messages to be sent to your home country as determined by the phone number you verified during signup. You can follow the steps in the following [How to change SMS Geo Permissions](#how-to-change-sms-geo-permissions) section to judiciously enable and disable SMS Geo Permissions by country.

> \[!WARNING]
>
> Each country has its own regulatory framework governing the use of SMS messages. Regulatory provisions may differ by sender type and use case. They may include additional registration requirements and define prohibited use cases.
>
> You are responsible for compliance with the applicable country-specific regulations. Review the [SMS Guidelines](https://www.twilio.com/en-us/guidelines/sms) for a country before you consider enabling its SMS Geo Permissions.

As you decide whether to enable SMS Geo Permissions for additional countries, make sure to review the [What's Next?](#whats-next) section at the end of this page for further guidance on ways to mitigate your risk exposure using Twilio products and best practices.

## How to change SMS Geo Permissions

> \[!NOTE]
>
> SMS Geo-Permissions can *not* be changed programmatically via the API for security reasons.

> \[!WARNING]
>
> Only users with [Account Owner and Account Admin profiles](https://help.twilio.com/hc/en-us/articles/223136227-What-s-the-Difference-Between-User-Roles-Owner-Administrator-Developer-Billing-Manager-and-Support-) can modify SMS Geo Permissions.

### Step 1 - Navigate to Messaging Geo Permissions settings

Ensure you are logged into the Twilio Account for which you want to change the permissions.

Navigate to **[Console > Messaging > Settings > Geo Permissions](https://console.twilio.com/us1/develop/sms/settings/geo-permissions)**.

![Geo permissions highlighted in messaging console side navigation.](https://docs-resources.prod.twilio.com/b82e2b77d65f6ab759d0135c00568530cb626cb9747d7146f6f215ee6c31b1f2.png)

### Step 2 - Adjust your SMS Geo Permission settings

> \[!NOTE]
>
> SMS Geographic Permissions generally work based on the country code of the destination phone number. However, exceptions exist for political and historical alignments and some may not map strictly to a country's political or cultural boundaries.

Find the country or region for which you want to adjust the SMS Geo Permissions. You can do so by scrolling through the displayed listing arranged by continent or you can use the **Filter by Country** input control to narrow the search.

Once you have found the country or region whose permissions you want to adjust, use the checkbox control next to its name to enable or disable it.

1. **Filter by country** control
2. **Country checkbox**

![Interface for adjusting SMS geo permissions with country filter and selection checkboxes.](https://docs-resources.prod.twilio.com/7c19c4ff11810903f2d55f8886a665bcfdf07cf2f24e1af39e05796bbd8b6185.png)

> \[!WARNING]
>
> Some countries or regions will have a **High Risk** marking next to their name. Twilio has assessed them to currently have the highest risk of [SMS Traffic Pumping Fraud](/docs/messaging/guides/preventing-messaging-fraud).
>
> As conditions change, e.g. due to enforcement actions or evolving bad actor behavior, Twilio's continuous monitoring activities may lead to adjustments of its risk assessments and result in changes to which countries or regions are marked as High Risk.
>
> Click on the **High Risk** marking to see a tooltip with additional information.
>
> ![Algeria marked high risk for SMS fraud with warning about fraudulent activity.](https://docs-resources.prod.twilio.com/52770fe897700010f53d0ec1250f0855b0860bc6403f283bb695b3c432f0cc57.png)

### Step 3 - Save your Geo Permission changes

Press the **Save geo permissions** button. An appropriate dialog opens to ask for your confirmation to proceed with saving the changes.

![Button labeled 'Save geo permissions' highlighted in blue.](https://docs-resources.prod.twilio.com/073a51de26d67b996068b54b26c1f87d373d4df4a726db076815e6b3ba6c2a07.png)

> \[!CAUTION]
>
> Saved changes to SMS Geo Permissions take effect immediately.
>
> As a result, as soon as you save the changes that disable the SMS Geo Permissions for a destination region, SMS to this destination will no longer be sent.
>
> When trying to send an SMS to a recipient (`to`) whose region has disabled SMS Geo Permissions, you will receive an [Error 21408](/docs/api/errors/21408).

#### Changes involving enabling High Risk Countries

If your changes include the enabling of SMS Geo Permissions for one or more countries that were marked **High Risk** for fraudulent activity, a **Risk Acknowledgement Confirmation Dialog** is shown. The dialog contains the list of affected countries and asks you to acknowledge:

* The resulting assumption of the increased risk and financial exposure
* Your responsibility to take actions to mitigate such risks.

If you decide to proceed, check the **I Acknowledge this risk checkbox** and then press the **Enable Geo Permissions** button.

Otherwise, press the **Cancel** button and return to [Step 2 - Adjust your SMS Geo Permission settings](#step-2---adjust-your-sms-geo-permission-settings).

1. **Risk exposure warning**
2. **List of high risk countries** to be enabled
3. **Risk acknowledgement checkbox**
4. **Enable geo permissions** button
5. **Cancel** button

![Dialog for enabling geo permissions with risk acknowledgment for Algeria.](https://docs-resources.prod.twilio.com/421ecfbdbe954037fa04cd45e5384c80425923f6ef27f6014a7f26e6ece97909.png)

#### Changes without enabling High Risk Countries

Even if your changes do not involve the enablement of high risk countries, a confirmation dialog is shown to remind you that saved geo permissions take immediate effect, including the blocking of SMS sent to disabled countries.

If you decide to proceed, press the **Update geo permissions** button.

Otherwise, press the **Cancel** button and return to [Step 2 - Adjust your SMS Geo Permission settings](#step-2---adjust-your-sms-geo-permission-settings).

1. **Update geo permissions** button
2. **Cancel** button

![Confirmation dialog for updating geo permissions with options to cancel or proceed.](https://docs-resources.prod.twilio.com/084d3689a58bd0e715bc2feaf9d410eab7765fc23bc4bb0599feb962b16060f8.png)

#### Successful updates

If a confirmed update to the SMS Geo Permissions is successful, the success alert **"Messaging geo permissions updated successfully"** appears in the top right corner of the screen.

![Messaging geo permissions updated successfully alert with close button.](https://docs-resources.prod.twilio.com/0655d23623dfed16d550f418841bdc3deb09b6e1454c1166a6ce73d31419f76f.png)

## Permissions inheritance with Subaccounts and Organizations

Depending on the complexity of your company or your use case, you may have decided to:

* Add [subaccounts under a Twilio account](https://help.twilio.com/hc/en-us/articles/360011132374-Getting-Started-with-Twilio-Accounts-and-Subaccounts) to [segment messaging activities for compliance or other business reasons](/docs/messaging/onboarding/build-your-account)
* [Manage multiple Twilio accounts using a Twilio Organization](/docs/iam/organizations).

If that is the case, it is important to understand the role of permissions inheritance.

### Subaccounts

By default a subaccount inherits the SMS Geo Permissions settings of its parent account. Inheritance is only possible between a single parent and its owned subaccounts.

To control the SMS Geo Permissions of a subaccount independently of its parent account, a user with [Account Owner or Account Administrator role](https://help.twilio.com/hc/en-us/articles/223136227-What-s-the-Difference-Between-User-Roles-Owner-Administrator-Developer-Billing-Manager-and-Support-) has to [disable inheritance for the subaccount](https://help.twilio.com/hc/en-us/articles/223135947-Do-subaccounts-support-international-calls-and-SMS-messaging-).

Then you are able to individually change the SMS Geo Permissions for the subaccount following the process described in [How to change SMS Geo Permissions](#how-to-change-sms-geo-permissions).

### Organizations

If you utilize a Twilio Organization to manage multiple accounts, each account will have its own separate SMS Geo Permissions settings independent of other accounts in the same organization.

No SMS Geo Permissions settings can be inherited from the organization-level.

As a result, you must manage each account's SMS Geo Permissions individually following the steps in [How to change SMS Geo Permissions](#how-to-change-sms-geo-permissions).

## Auditing SMS Geo Permission changes

You may wish to review which changes were made to SMS Geo Permissions. Event logs for SMS Geo Permission changes can be found in Console or requested programmatically using the [Monitor Event REST API resource](/docs/usage/monitor-events).

### Console

In order to audit SMS Geo Permission changes in Console, you can follow these steps:

1. Ensure you are Logged into Console with the Twilio Account you want to audit.
2. Navigate to the [**Monitor > Insights > Audit > Audit Event Logs**](https://console.twilio.com/us1/monitor/insights/audit/reports/RJ6c4330a5f3cde94588f040e35d127ee6) report.
3. Set the **Start Date** and **End Date** to narrow the period you want to audit.
4. Find and review entries with **Event Type** values of

   * `sms-geographic-permissions.created`
   * `sms-geographic-permissions.deleted`
   * `sms-geographic-permissions.updated`
5. Click on an entry's **Event SID** to see full details of the SMS Geo Permissions Change.

![Audit Events Log showing event types over time with date range from 2023-10-15 to 2023-11-14.](https://docs-resources.prod.twilio.com/e3537f2903bca10c1aa0d35f670353e8b5abdfa670d8fcf0951a347afe783e1f.png)

The audit event details include:

* Event date and time
* **Resource Type** and **Event Type**
* Information about who made the change (**Actor SID**, **Actor** and **Source IP Address**)

For updated SMS Geo Permissions, the **Property** column of the **Changes** table will contain the name of the country for which a change was made and its **Previous Value** and **Updated Value**.

![Geo permissions audit showing Greenland status changed from enabled to disabled.](https://docs-resources.prod.twilio.com/f06325c4c434036d16fd9f11f87c1226234d67381d27103757e096b259cedd7b.png)

### Monitor Event API

The Monitor Event API resource allows you to [Read a list of monitored events](/docs/usage/monitor-events#read-multiple-event-resources) for certain [resource types and associated event types](/docs/usage/monitor-events#event-types). Specifically for changes to the SMS Geo Permissions, you can obtain events for the resource type `sms-geographic-permissions` which is associated with the following three event types:

* `sms-geographic-permissions.created`
* `sms-geographic-permissions.deleted`
* `sms-geographic-permissions.updated`

Use the [EventType parameter of the Read action](/docs/usage/monitor-events#read-multiple-event-resources) to get a list of filtered SMS Geo Permission change events for any one of these event type values. To only see events within a specific time frame, you can additionally use the `StartDate` and `EndDate` parameters.

## What's Next?

Now that you know which role SMS Geo Permissions play and how to manage them, check out the following information to further protect yourself from SMS-based fraud:

* Read our guidance on [Preventing Fraud](/docs/messaging/guides/preventing-messaging-fraud) and [SMS Pumping Protection for Programmable Messaging](/docs/messaging/features/sms-pumping-protection-programmable-messaging)
* Explore the use of [Verify](/docs/verify) and its [Verify Fraud Guard](/docs/verify/preventing-toll-fraud/sms-fraud-guard) feature
* Follow our [Anti-Fraud Developer's Guide](/docs/usage/anti-fraud-developer-guide) for comprehensive guidance