Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Notify API Binding Resource


The Binding resource binds an identity to the address used by a notification channel. For example, iOS push notifications use an APNS device token for their address and SMS uses a phone number. Creating a Binding allows you to send notifications by referring to an identity rather than a specific device. You can create up to 20 Bindings with the same identity in a given Service.

You can add tags to a Binding that describe related Bindings. For example, you can add a tag to the Bindings of a user's preferred devices and then refer to that tag to notify them on only their preferred devices. Read more about Sending Notifications.

(error)

Danger

Do not use Personally Identifiable Information (PII) for identity.

The systems that process this parameter assume it does not contain PII.

You should use a GUID or other pseudonymized identifier for identity instead of PII such as a person's name, home address, email or phone number. If you identify your users with PII, we recommend creating a pseudonymized identifier from their PII, for example by hashing or encrypting it, before you use it for identity.

You can read more about how we process your data in our privacy policy.

(warning)

Warning

Make sure you have consent from users before storing their device's address.

It's a good practice to obtain your end users' consent before you send them messages and some jurisdictions might require it by law.

We recommend that you consult with your legal counsel to make sure that your communications comply with all applicable laws.

To make sure your messages reach the right people, you should make sure that they have given you their consent to send them messages and that their contact information is current.

Check out the Twilio Marketplace for Add-ons from our partners that can help you keep your database up to date.


Address for push notifications

address-for-push-notifications page anchor

While the address of an SMS message is the phone number, the address to use for push notifications is obtained by your client-side mobile app. Learn how to:


Resource properties
sidtype: SID<BS>Not PII

The unique string that we created to identify the Binding resource.


service_sidtype: SID<IS>Not PII

The SID of the Service(link takes you to an external page) the resource is associated with.


credential_sidtype: SID<CR>Not PII

The SID of the Credential(link takes you to an external page) resource to be used to send notifications to this Binding. If present, this overrides the Credential specified in the Service resource. Applicable only to apn, fcm, and gcm type Bindings.


date_createdtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was created specified in RFC 2822(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822(link takes you to an external page) format.


notification_protocol_versiontype: stringNot PII

The protocol version to use to send the notification. This defaults to the value of default_xxxx_notification_protocol_version in the Service(link takes you to an external page) for the protocol. The current version is "3" for apn, fcm, and gcm type Bindings. The parameter is not applicable to sms and facebook-messenger type Bindings as the data format is fixed.


endpointtype: stringNot PII

Deprecated.


identitytype: stringPII MTL: 120 days

The identity value that uniquely identifies the resource's User(link takes you to an external page) within the Service(link takes you to an external page). Up to 20 Bindings can be created for the same Identity in a given Service.


binding_typetype: stringNot PII

The transport technology to use for the Binding. Can be: apn, fcm, gcm, sms, or facebook-messenger.


addresstype: stringPII MTL: 120 days

The channel-specific address. For APNS, the device token. For FCM and GCM, the registration token. For SMS, a phone number in E.164 format. For Facebook Messenger, the Messenger ID of the user or a phone number in E.164 format.


tagstype: string[]PII MTL: 120 days

The list of tags associated with this Binding. Tags can be used to select the Bindings to use when sending a notification. Maximum 20 tags are allowed.


urltype: string<URI>Not PII

The absolute URL of the Binding resource.


linkstype: object<URI MAP>Not PII

The URLs of related resources.

Endpoint (DEPRECATED)

endpoint-deprecated page anchor

We deprecated endpoint and trust the push-channel provider (such as APNS or Firebase) to let us know when an app has changed or invalidated the device token used as the address.

The endpoint property was used to uniquely identify push notification Bindings when the app installation's address changed, such as when the device token changed in an iOS app. You can still include an Endpoint parameter when you create a Binding; however, it will be ignored.


Create a Binding resource

create-a-binding-resource page anchor
POST https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings

Parameters

create-parameters page anchor
URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to create the resource under.


Request body parameters
Identitytype: stringPII MTL: 120 days
Required

The identity value that uniquely identifies the new resource's User(link takes you to an external page) within the Service(link takes you to an external page). Up to 20 Bindings can be created for the same Identity in a given Service.


BindingTypetype: enum<STRING>Not PII
Required

The transport technology to use for the Binding. Can be: apn, fcm, gcm, sms, or facebook-messenger.

Possible values:
apngcmsmsfcmfacebook-messengeralexa

Addresstype: stringPII MTL: 120 days
Required

The channel-specific address. For APNS, the device token. For FCM and GCM, the registration token. For SMS, a phone number in E.164 format. For Facebook Messenger, the Messenger ID of the user or a phone number in E.164 format.


Tagtype: string[]Not PII

A tag that can be used to select the Bindings to notify. Repeat this parameter to specify more than one tag, up to a total of 20 tags.


NotificationProtocolVersiontype: stringNot PII

The protocol version to use to send the notification. This defaults to the value of default_xxxx_notification_protocol_version for the protocol in the Service(link takes you to an external page). The current version is "3" for apn, fcm, and gcm type Bindings. The parameter is not applicable to sms and facebook-messenger type Bindings as the data format is fixed.


CredentialSidtype: SID<CR>Not PII

The SID of the Credential(link takes you to an external page) resource to be used to send notifications to this Binding. If present, this overrides the Credential specified in the Service resource. Applies to only apn, fcm, and gcm type Bindings.


Endpointtype: stringNot PII

Deprecated.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.bindings
_15
.create({
_15
identity: 'identity',
_15
bindingType: 'apn',
_15
address: 'address'
_15
})
_15
.then(binding => console.log(binding.sid));

Output

_20
{
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"address": "a7c658f4111ec4ff5a1a647f9d0edd819025b9f20522d2fae897049f32873e73",
_20
"binding_type": "apn",
_20
"credential_sid": null,
_20
"date_created": "2015-07-30T20:00:00Z",
_20
"date_updated": "2015-07-30T20:00:00Z",
_20
"endpoint": "26607274",
_20
"identity": "24987039",
_20
"notification_protocol_version": "3",
_20
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"sid": "BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"tags": [
_20
"26607274"
_20
],
_20
"links": {
_20
"user": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users/24987039"
_20
},
_20
"url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings/BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_20
}


Existing Bindings with the same Address are replaced

existing-bindings-with-the-same-address-are-replaced page anchor

If the Service already has a Binding with the same Address as specified in the create request, the Binding being created replaces the existing Binding.

The new Binding replaces the existing one under these conditions to prevent leaking notifications between users when, for example, a new user logs into your app on a device that has already been registered to another user.

To register the same address twice, such as when someone is a buyer and a seller at the same time in a marketplace, we recommend creating separate Service instances, such as one for buyers and one for sellers.


We deprecated endpoint and trust the push-channel provider (such as APNS or Firebase) to let us know when an app has changed or invalidated the device token used as the address.

The endpoint property was used to uniquely identify push notification Bindings when the app installation's address changed, such as when the device token changed in an iOS app. You can still include an Endpoint parameter when you create a Binding; however, it will be ignored.


Fetch a Binding resource

fetch-a-binding-resource page anchor
GET https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings/{Sid}

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to fetch the resource from.


Sidtype: SID<BS>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the Binding resource to fetch.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.bindings('BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(binding => console.log(binding.sid));

Output

_20
{
_20
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"address": "a7c658f4111ec4ff5a1a647f9d0edd819025b9f20522d2fae897049f32873e73",
_20
"binding_type": "apn",
_20
"credential_sid": null,
_20
"date_created": "2015-07-30T20:00:00Z",
_20
"date_updated": "2015-07-30T20:00:00Z",
_20
"endpoint": "26607274",
_20
"identity": "24987039",
_20
"notification_protocol_version": "3",
_20
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"sid": "BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_20
"tags": [
_20
"26607274"
_20
],
_20
"links": {
_20
"user": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users/24987039"
_20
},
_20
"url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings/BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_20
}


Read multiple Binding resources

read-multiple-binding-resources page anchor
GET https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to read the resource from.


StartDatetype: string<DATE>Not PII
Query Parameter

Only include usage that has occurred on or after this date. Specify the date in GMT and format as YYYY-MM-DD.


EndDatetype: string<DATE>Not PII
Query Parameter

Only include usage that occurred on or before this date. Specify the date in GMT and format as YYYY-MM-DD.


Identitytype: string[]PII MTL: 120 days
Query Parameter

The User(link takes you to an external page)'s identity value of the resources to read.


Tagtype: string[]Not PII
Query Parameter

Only list Bindings that have all of the specified Tags. The following implicit tags are available: all, apn, fcm, gcm, sms, facebook-messenger. Up to 5 tags are allowed.


PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

Read multiple Binding resources

read-multiple-binding-resources-1 page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.bindings
_11
.list({limit: 20})
_11
.then(bindings => bindings.forEach(b => console.log(b.sid)));

Output

_33
{
_33
"bindings": [
_33
{
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"address": "a7c658f4111ec4ff5a1a647f9d0edd819025b9f20522d2fae897049f32873e73",
_33
"binding_type": "apn",
_33
"credential_sid": null,
_33
"date_created": "2015-07-30T20:00:00Z",
_33
"date_updated": "2015-07-30T20:00:00Z",
_33
"endpoint": "26607274",
_33
"identity": "24987039",
_33
"notification_protocol_version": "3",
_33
"service_sid": "ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"sid": "BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"tags": [
_33
"26607274"
_33
],
_33
"links": {
_33
"user": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Users/24987039"
_33
},
_33
"url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings/BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_33
}
_33
],
_33
"meta": {
_33
"first_page_url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings?Tag=tag&Identity=identity&PageSize=50&Page=0",
_33
"key": "bindings",
_33
"next_page_url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings?Tag=tag&Identity=identity&PageSize=50&Page=1",
_33
"page": 0,
_33
"page_size": 50,
_33
"previous_page_url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings?Tag=tag&Identity=identity&PageSize=50&Page=0",
_33
"url": "https://notify.twilio.com/v1/Services/ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Bindings?Tag=tag&Identity=identity&PageSize=50&Page=0"
_33
}
_33
}

Note that no more than 50 Bindings are returned at a time.


Delete a Binding resource

delete-a-binding-resource page anchor
DELETE https://notify.twilio.com/v1/Services/{ServiceSid}/Bindings/{Sid}

URI parameters
ServiceSidtype: SID<IS>Not PII
Path Parameter

The SID of the Service(link takes you to an external page) to delete the resource from.


Sidtype: SID<BS>Not PII
Path Parameter

The Twilio-provided string that uniquely identifies the Binding resource to delete.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.notify.v1.services('ISXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.bindings('BSXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.remove();


Rate this page: