Skip to main content

Retrieve an SMS opt-out suppression list

Feature coming soon: This feature is available to customers in all Genesys Cloud regions except Canada Central 1 Region (CAC1) and FedRAMP.

Customers can retrieve a list of phone numbers that have opted out of SMS messaging to support audits and reconcile internal records.

Note: In some cases, external SMS providers manage opt-out requests directly. As a result, the suppression list may not include opt-out records maintained by those providers. For questions or assistance with reviewing and reconciling suppression data, contact

Genesys Cloud provides a GET API to access the suppression list:

GET /api/v2/routing/sms/phonenumbers/{phoneNumberId}/suppression

This endpoint requires the SMS > optOut > view permission and the following OAuth scope:

Scopes.ROUTING_READONLY

The GET API will return the following fields:

FieldDescription

contactPhoneNumber

E.164 formatted phone number of the opted-out device.

phoneNumber

E.164 formatted SMS sender.

optOutTime

Timestamp when the opt-out was recorded.

optOutMessageId

ID of the message that triggered the opt-out.

You can filter results by the contactPhoneNumber query parameter (in E.164 format, for example +1234567890). Pagination is also supported using the pageNumber and pageSize queryparameters.