Introduction
AT&T Dynamic Traffic Management APIs enable application developers managing application data traffic to get enhanced Quality of Service (QoS) treatment on the AT&T-owned domestic 4G LTE network, thereby enabling customers to better manage their business application data traffic during times of network congestion. These APIs support functionalities such as checking eligibility for a given subscriber, managing QoS sessions, sending notifications regarding the customer session usage and retrieving usage details for a subscriber.
API Quick Start
Get App Key & App Secret
To start working with AT&T APIs, create a developer account or sign in to your existing account on the AT&T Developer Program website.
Click on the My Apps selection and click "Set Up New App" on My Apps page by providing an Application Name. Then, choose the one or more of the following from the list of available services and click submit to get an App Key and App Secret.
Get OAuth Access Token
AT&T uses the OAuth 2.0 framework to obtain an OAuth access token as shown in this call flow. To obtain an access token, use the following OAuth sample code:
Make API Calls
The create session API creates a Dynamic Traffic Management session for an AT&T subscriber to receive a priority treatment on the 4G LTE network.
Oauth
All APIs provided by AT&T use the OAuth 2.0 framework. All API requests sent to the API Gateway must include an OAuth access token. You may authorize access for this API by using the following scopes.
- NOTIFICATIONCHANNEL, SESSIONS:ADTM - To manage notifications
- CONSENTED:PROFILES:USAGE – To retrieve the subscriber level session usage details
The Get Session Eligibility method enables an application or developer to get the subscriber’s eligibility information before creating a session. If the subscriber is eligible, the operation returns “true” in the “eligibility” response parameter. If the subscriber is ineligible to create a session, then the operation returns list of reason codes in the response
OAuth Scope
[The Oauth portion of documentation found here requires sign in to view.]
Resource URL
GET https://api.att.com/sessionManagement/v2/eligibility
Request
GET /sessionManagement/v2/eligibility HTTP/1.1
Host: api.att.com
Authorization: Bearer Y3BzOmNwczEyMw==
Accept: application/json
x-att-service : adtm
Response - ineligible subscriber
HTTP(S)/1.1 200 OK { "sessionEligibility": { "serviceId": "adtm", "isEligible": false, "ineligibilityReason": [ { "code": "RSN - 1115", "description": "Maximum session usage or spend limit reached." }, { "code": "RSN - 1116", "description": "Not authorized for session usage." }, { "code": "RSN - 1117", "description": "ADTM Policy is turned Off." } ] } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response.
Accepted value: application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 401 Unauthorized message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
x-att-service
String
Yes
Specifies the service name to use this API.
Supported services:
- adtm
Header
Response Parameters
Parameter
Data Type
Req?
Brief description
sessionEligiblity
Object
Yes
Specifies the eligibility object.
Object: sessionEligibility
Parameter
Data Type
Req?
Brief description
serviceId
String
Yes
Specifies service identifier.
isEligible
Boolean
Yes
Indicates whether subscriber is eligible to sign up for specified service.
entitlements
Array of entitlement object
Cond
Contains list of network entitlement objects.
ineligibilityReasons
Array of ineligibilityReason Object
Cond
Specifies list of ineligibility reason(s).
Note: This information is returned when the parameter isEligible=false;
Object: entitlement
Parameter
Data Type
Req?
Brief description
classOfService
String
No
Specifies network class of service
bearerType
String
No
Specifies network bearer type
downlinkBitRate
Integer
No
Specifies bearer downlink bit rate
uplinkBitRate
Integer
No
Specifies bearer uplink bit rate
Object: ineligibilityReason
Parameter
Data Type
Req?
Brief description
code
String
Yes
Specifies ineligibility reason code.
description
String
Yes
Specifies ineligibility reason description.
OAuth Scope
[The Oauth portion of documentation found here requires sign in to view.]
Resource URL
POST https://api.att.com/sessionManagement/v2/sessions
Request – Creating a device level QoS session
POST /sessionManagement/v2/sessions HTTP 1.1 Authorization: Bearer Y3BzOmNwczEyMw== Content-Type: application/json Accept: application/json x-att-service: adtm
Response
HTTP(S)/1.1 202 Accepted { "session": { "serviceId": "adtm", "sessionId": "{session_identifier}", "status": "Pending" } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Accepted value: application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 401 Unauthorized message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
x-att-service
String
Yes
Specifies the service name to use this API.
Supported services:
- adtm
Header
session
Object
Yes
Specifies the session object.
Body
Object: session
Parameter
Data Type
Req?
Brief description
apn
String
Cond
Specifies an Access Point Name value.
classOfService
String
Cond
Specifies network Class of Services.
duration
Integer
Cond
Specifies the session duration in seconds ex: 3600 seconds
Note: This parameter should not be passed if the volume parameter is already defined in the request.
volume
Integer
Cond
Specifies session volume in kilobytes ex. 100kb
Note: This parameter should not be passed if the duration parameter is already defined in the request.
applicationId
String
No
Specifies name of the sponsor of the QoS change
bearerType
String
No
Specifies the bearer types.
connectionDetails
connectionDetail object
Cond
Contains connection details values
Note: valid only when bearerType = dedicated; Developer cannot modify this object in the update call.
Object: connectionDetail
Parameter
Data Type
Req?
Brief description
ip
String
Yes
Specifies the ip value.
port
String
Yes
Specifies the ip port value
protocol
String
Yes
Specifies the protocol value.
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
session
Object
Yes
Specifies the session object.
Body
Object: session
Parameter
Data Type
Req?
Brief description
serviceId
String
Yes
Specifies the service identifier.
Note: Will be present in the response. This parameter cannot be updated.
sessionId
String
Yes
Specifies the Session Identifier
Note: Will be present in the response. This parameter cannot be updated.
status
String
Yes
Specifies session status.
Valid values:
- "defined"
- "error"
- "pending"
Note: Will be present in the response. This parameter cannot be updated.
The Get Session method enables an application or developer to retrieve the details of an existing session.
OAuth Scope
[The Oauth portion of documentation found here requires sign in to view.]
Resource URL
GET https://api.att.com/sessionManagement/v2/sessions/{session_identifier}
Request
GET /sessionManagement/v2/sessions/{session_identifier} Authorization: Bearer Y3BzOmNwczEyMw== Accept: application/json x-att-service: adtm
Response
HTTP(S)/1.1 200 OK { "session": { "serviceId": "adtm", "sessionId": "{session_identifier}", "status": "defined", "apn": "{apn_value}", "classOfService": "{cos_value}", "duration": 3600, "applicationId": "application123", "bearerType": "dedicated", "connectionDetails": { "ip": "0.0.0.0", "port": "8080", "protocol": "17" } } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Accepted value: application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 401 Unauthorized message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
x-att-service
String
Yes
Specifies the service name to use this API.
Supported services:
- adtm
Header
sessionId
String
Yes
Specifies the session identifier.
URI
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
session
Object
Yes
Specifies the session object.
Body
Object: session
Parameter
Data Type
Req?
Brief description
serviceId
String
Cond
Specifies the service identifier.
sessionId
String
Cond
Specifies the service identifier.
apn
String
Cond
Specifies an Access Point Name value.
classOfService
String
Cond
Specifies network Class of Services.
duration
Integer
Cond
Specifies the session duration in seconds ex: 3600 seconds
volume
Integer
Cond
Specifies session volume in kilobytes ex. 100kb
applicationId
String
No
Specifies name of the sponsor of the QoS change
bearerType
String
No
Specifies the bearer types. Valid values:
- default
- dedicated
connectionDetails
connectionDetail object
Cond
Contains connection details values
status
String
Cond
Specifies session status.
Valid values:
- "defined"
- "error"
- "pending"
Object: connectionDetail
Parameter
Data Type
Req?
Brief description
ip
String
Yes
Specifies the ip value.
port
String
Yes
Specifies the ip port value.
protocol
String
Yes
Specifies the protocol value.
The update session method enables an application of developer to update the details of an existing session. This method only allows a developer to modify Class of Service (CoS), APN and duration or volume.
OAuth Scope
[The Oauth portion of documentation found here requires sign in to view.]
Resource URL
PUT https://api.att.com/sessionManagement/v2/sessions/{sessions_identifier}
Request
PUT /sessionManagement/v2/sessions/{session_identifier} Authorization: Bearer Y3BzOmNwczEyMw== Content-Type: application/json Accept: application/json x-att-service: adtm { "session": { "classOfService": "{cos_value}", "apn": "{apn_value}", "duration": 3600 } }
Response
HTTP(S)/1.1 202 Accepted { "session": { "serviceId": "adtm", "sessionId": "{session_identifier}", "status": "Pending" } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Accepted value: application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 401 Unauthorized message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
sessionId
String
Yes
Specifies the session identifier.
URI
session
Object
Yes
Specifies the session object
Body
Object: session
Parameter
Data Type
Req?
Brief description
apn
String
Cond
Specifies an Access Point Name value.
classOfService
String
Cond
Specifies network Class of Services.
duration
Integer
Cond
Specifies the session duration in seconds. Ex. 3600 seconds
Note: a) This parameter should not be passed if the volume parameter is already defined in the request.
volume
Integer
Cond
Specifies session volume in kilobytes ex. 100kb
Note: a) This parameter should not be passed if the duration parameter is already defined in the request.
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
session
Object
Yes
Specifies the session object.
Body
Object: session
Parameter
Data Type
Req?
Brief description
serviceId
String
Yes
Specifies the service identifier.
sessionId
String
Yes
Specifies the Session identifier.
status
String
Yes
Specifies session status.
Valid values:
- "defined"
- "error"
- "pending"
The delete session method enables an application or developer to deletes an active or existing session.
OAuth Scope
[The Oauth portion of documentation found here requires sign in to view.]
Resource URL
DELETE https://api.att.com/sessionManagement/v2/sessions/{session_identifier}
Request
DELETE /sessionManagement/v2/sessions/{session_identifier} Authorization: Bearer Y3BzOmNwczEyMw== Accept: application/json x-att-service: adtm
Response
HTTP(S)/1.1 202 Accepted { "session": { "serviceId": "adtm", "sessionId": "{session_identifier}", "status": "Pending" } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Accepted value: application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 401 Unauthorized message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
x-att-service
String
Yes
Specifies the service name to use this API.
Supported services:
- adtm
Header
sessionId
String
Yes
Specifies the session identifier.
URI
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-length
Integer
No
Specifies the length of the content in octets. This header parameter is only required for the non-streaming request.
Header
content-type
String
No
Specifies the type of content of the body of the entity. Accepted value: application/json
Header
session
Object
Yes
Specifies the session object.
Body
Object: session
Parameter
Data Type
Req?
Brief description
serviceId
String
Yes
Specifies the service identifier.
sessionId
String
Yes
Specifies the Session identifier.
status
String
Yes
Specifies session status.
Valid values:
- "defined"
- "error"
- "pending"
The Get Session Usage details method enables an application or developer to retrieve the session usage details for a given subscriber.
OAuth Scope
Scope: CONSENTED:PROFILES:USAGE
Resource URL
GET https://api.att.com/accountSecuredDetails/v2/profiles?profileType=subscriberUsage
Request
GET /accountSecuredDetails/v2/profiles?profileType=subscriberUsage HTTP/1.1 Host: api.att.com Accept : application/json Authorization: Bearer abcd123456dfeswswderewr254
Response
HTTP/1.1 200 OK Content-Type: application/json Content-Length: 66 Date: Thu, 04 Aug 2017 02:51:59 GMT { "profiles":{ "subscriberUsage":{ "phoneNumber":"1234569870", "spendAndUsageCap":{ "cycleStartDate":"", "OfferSummary":{ "offerCode":"323612185", "offerDescription":"Offer description", "offerEffectiveDate":"2017-07-31Z", "offerExpirationDate":"2020-12-31Z", "eventsThrough":"2007-07-21T15:01:01Z", "usageDetail":{ "usageCategory":"GS", "roamingIndicator":"H", "unitOfMeasure":"dollars", "allotedUnits":"352", "usedUnits":"80", "remainingUnits":"272", "actualUnits":"352", "overageUnits":"" }, "chargeAmount":0 } } } } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies "Bearer" + OAuth Token – access_token. If the Authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message along with a WWW-Authenticate HTTP header
Header
profileType
String
Yes
Specifies type of profile to be returned. Types of profile: subscriberUsage
QueryString
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
profiles
Object
Yes
Contains Profiles Information.
Body
Object: profiles
Parameter
Data Type
Req?
Brief description
Location
subscriberUsage
Object
Cond
Contains subscriber usage information
Body
Object : subscriberUsage
Parameter
Data Type
Req?
Brief description
Location
phoneNumber
String
Yes
Specifies subscriber phone number
Body
spendAndUsageCap
Object
No
Contains spend and usage details
Body
Object : spendAndUsageCap
Parameter
Data Type
Req?
Brief description
Location
offerSummary
Object
No
Contains offer summary details
Body
cycleStartDate
Date
No
Specifies billing cycle start date
Body
Parameter
Data Type
Req?
Brief description
Location
offerCode
String
No
Specifies a numerical value that identifies/represents a particular usage cap type (i.e. one numerical value for a $ cap amount, or another for data volume cap amount).
Body
offerDescription
String
No
Specifies price plan description
Body
offerEffectiveDate
Timestamp
No
Specifies offer start date
Body
offerExpirationDate
Timestamp
No
Specifies offer end date
Body
eventsThrough
Timestamp
No
Specifies the date and time up to which the response data is addressing.
Body
usageDetail
Object
No
Specifies spend and usage cap details. This object returns
a)usage cap details which is tied-up with MRC/flat rate to protect AT&T from customer over using data
b)spend cap details which is tied-up to PPU to protect customer from over using data to avoid getting a huge bill.
Body
chargeAmount
Integer
No
Specifies charge amount for a given account.
Body
Object : usageDetail
Parameter
Data Type
Req?
Brief description
Location
usageCategory
String
No
Specifies type of cap (limit), through one of the following possible values:
- GS: Global Spending Cap in $ amount - “Global” are default cap limits imposed by ATT when the subscriber opts to forego setting a cap themselves.
- GU: Global Usage in data volume
- SS: Subscriber defined spending limit in $ amount
SU: Subscriber or SOC usage limit in $ amount
Body
roamingIndicator
String
No
Specifies romaing value of athe subscriber.
valid value: H ( Home )
Body
unitOfMeasure
String
No
Specifies spend and usage data is addressing ($) or data volume units
Body
allotedUnits
String
No
Specifies quantity of spend or usage data allotted
Body
usedUnits
String
No
Specifies quantity of spend or usage data used
Body
remainingUnits
String
No
Specifies quantity of spend or usage data remaining
Body
actualUnits
String
No
Specifies quantity of spend or usage data allotted
Body
overageUnits
String
No
Specifies overage units.
Body
The Create Channel method will create a Notification Channel resource. Once a Channel is setup it should be used all subsequent interaction with the Push Notifications API. So, this operation should be used to during the bootstrap process. Only one channel is allowed per app key/secret.
OAuth Scope
Scope: NOTIFICATIONCHANNEL | Model: Client Credential
Resource URL
POST https://api.att.com/notification/v2/channels
Request
POST /notification/v2/channels HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json content-type: application/json { "channel": { "serviceName": "ADTM", "notificationContentType": "application/json" "notificationVersion": 1.0 } }
Response
HTTP/1.1 201 Created content-type: application/json location: https://api.att.com/notification/v2/channels/{channelId} x-systemTransactionId: trans12345678 { "channel": { "channelId": "{channelId}", "maxEventsPerNotification": 20 } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
channel
Object
Yes
Specifies information about the Notification Channel
Body
Object: channel
Parameter
Data Type
Req?
Brief description
Location
serviceName
String
Yes
Specifies service name. (ADTM)
Header
notificationContentType
String
No
Specifies the type of content of the body of the notification messages that will be sent to the subscribing application through the Notification Channel. Must be set to one of the following values:
- application/json
Body
notificationVersion
Decimal
No
Specifies the version of the push notification payload. Acceptable values:
- 1.0 - API version v1
Body
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
location
String
Yes
Specifies the location of the Notification Channel
Header
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
channel
Object
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Body
Object: channel
Parameter
Data Type
Req?
Brief description
Location
channelId
String
Yes
Specifies the unique Id of the Notification Channel
Body
maxEventsPerNotification
Integer
No
Specifies the maximum number of notification messages that will be included in any single Notification sent to the subscribing application through the Notification Channel.
Body
The Get Channel method can be used by an app to retrieve its Notification Channel details. The Channel resource returned by this operation is actively being used by the Push Notification API for any existing Notification Subscriptions, and should be used to create more new Notification Subscriptions for the same service.
If no Notification Channel resource is returned (404 Not Found) it implies that either no Notification Channel has been created for the app, or the Notification Channel has been deleted/closed. Either way it also implies that there are no Notification Subscriptions registered for the app, and it will not receive any Push Notifications.
OAuth Scope
Scope: NOTIFICATIONCHANNEL | Model: Client Credential
Resource URL
GET https://api.att.com/notification/v2/channels/{channelId}
Request
GET /notification/v2/channels/{channelId} HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json
Response
HTTP/1.1 200 OK content-type: application/json x-systemTransactionId: trans12345678 { "channel": { "channelId": "{channelId}", "maxEventsPerNotification": 20, "serviceName": "ADTM", "channelType": "http_callback", "notificationContentType": "applicaton/json", "notificationVersion": 1.0 } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
channelId
String
Yes
Specifies the unique Id of the Notification Channel
URI
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
location
String
Yes
Specifies the location of the Notification Channel
Header
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
channel
Object
Yes
Specifies information about the Notification Channel
Body
Object: channel
Parameter
Data Type
Req?
Brief description
Location
channelId
String
Yes
Specifies the unique Id of the Notification Channel
Body
maxEventsPerNotification
Integer
No
Specifies the maximum number of notification messages that will be included in any single Notification sent to the subscribing application through the Notification Channel.
Body
serviceName
String
Yes
Specifies the name of the AT&T API which will be originating the events that the app wishes to receive. The value of this parameter will match the scopes that the service will require in order to create events for the Push Notifications.
Body
notificationContentType
String
No
Specifies the type of content of the body of the notification messages that will be sent to the subscribing application through the Notification Channel.
Body
notificationVersion
Decimal
No
Specifies the version of the push notification payload.
Body
channelType
String
No
Specifies the protocol that will be used to deliver the Push Notifications.
Body
The Delete Notification Channel method enables developer or an application to delete the Notification Channel. This operation results in dependent Notification Subscriptions being deleted as well. No further notifications will be delivered after deleting a channel. To receive future notifications a notification channel must be recreated and all users must be presubscribed as well.
OAuth Scope
Scope: NOTIFICATIONCHANNEL | Model: Client Credential
Resource URL
DELETE https://api.att.com/notification/v2/channels/{channelId}
Request
DELETE /notification/v2/channels/{channelId} HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json
Response
HTTP/1.1 204 No Content x-systemTransactionId: trans12345678
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
channelId
String
Yes
Specifies the unique Id of the Notification Channel
URI
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
The Create Notification Subscription operation allows the DHS to create a subscription on a Notification Channel, in order to receive push notifications for specified events. The scope and oAuth type for creating a notification subscription depends on the calling API, which is specified by service name for the notification channel.
Each Subscription has a TTL (Time to live i.e. expiresIn). Notifications will be delivered to the DHS callback URL from the time the subscription is successful till the time the TTL expires. Either the Subscription should be renewed before it expires, or should be recreated after it expires in order to continue receiving push notifications. The app developer may request a specific TTL, however it is up to the service to honor the request.
ADTM API supports push notifications for events on a subscriber's Session events. Based on the type of subscription event created, the notifications can be sent for the following types of events -
- "ADTM_USAGE_CAP": this value indicates the percentage threshold for usage that has been exceeded.
- "ADTM_SPEND_CAP": this value indicates the percentage threshold for spending limit that has been exceeded.
- "ADTM_SESSION": this value indicates the status returned when a notification is triggered by creation of an On-Demand session.
OAuth Scope
Scope: SESSIONS:ADTM
Resource URL
POST https://api.att.com/notification/v2/channels/{channelId}/subscriptions
Request
POST /notification/v2/channels/{channelId}/subscriptions HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json content-type: application/json { "subscription": { "events": [ "ADTM_SPEND_CAP", "ADTM_USAGE_CAP", "ADTM_SESSION" ], "callbackData" : "unique_user_id", "expiresIn": 16836 } }
Response
HTTP/1.1 201 Created Content-Type: application/json Location: /notification/v2/channels/{channelId}/subscriptions/{subscriptionId} x-systemTransactionId: apptrans12345678 { "subscription": { "subscriptionId": "{subscriptionId}", "expiresIn": 86400 } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
channelId
String
Yes
Specifies the unique Id of the Notification Channel in which the subscription is created.
URI Path
subscription
Subscription Object
Cond
The object that contains the subscription data.
Body
Object: subscription
Parameter
Data Type
Req?
Brief description
Location
events
String Array
Yes
Specifies kind of events that the application developer is interested in subscribing for notifications.
Valid values for ADTM :
- "ADTM_USAGE_CAP": ADTM usage threshold events
- "ADTM_SPEND_CAP": ADTM spend cap events
- "ADTM_SESSION": ADTM On-Demand session status events
Body
callbackData
String
Cond
This is an optional piece of data that the DHS can pass to the Subscription and expect to be returned along with any events specific to the Subscription. The callback data cannot exceed 50 characters.
Note: An empty string value is assumed if no value was passed.
Body
expiresIn
Integer
Cond
An integer value specifying the proposed time-to-live (in seconds) for the subscription. Valid values are
- 0 - indicates subscription will never expire
- A value between 3600 (1 hour) and 31536000 (1 year)
- If not specified the default value is 3600 seconds (1 hour).
The service will decide whether to honor the proposed value based on its policies.
Body
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
location
String
Yes
Returns the location of the newly created notification subscription.
Header
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
subscription
Subscription Object
Yes
Returns the subscription object.
Body
Object: subscription
Parameter
Data Type
Req?
Brief description
Location
subscriptionId
String
Yes
Returns the ID for the newly created subscription.
Body
expiresIn
Integer
No
An integer value that represents the time remaining in seconds in which the subscription will expire. When the subscription expires the developer server is expected to renew the subscription by invoking the Update Subscription Notification call.
Body
The Get Notification Subscription operation can be used by an app to get a previously created Notification Subscriptions details. This operation will error if the specified Notification Subscription could not be located.
OAuth Scope
Scope: SESSIONS:ADTM
Resource URL
GET https://api.att.com/notification/v2/channels/{channelId}/ subscriptions/{subscriptionId}
Request
GET /notification/v2/channels/{channelId}/subscriptions/{subscriptionId} HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json
Response
HTTP/1.1 200 OK Content-Type: application/json x-systemTransactionId: apptrans12345678 { "subscription": { "subscriptionId": "{subscriptionId}", "expiresIn": 86400, "events": [ "ADTM_SPEND_CAP", "ADTM_USAGE_CAP", "ADTM_SESSION" ] "callbackData" : "unique_user_id" } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
channelId
String
Yes
Specifies the unique Id of the Notification Channel in which the subscription is created.
URI Path
subscriptionId
String
Yes
Specifies the unique Id of the notification subscription.
URI Path
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
subscription
Subscription Object
Yes
Returns the subscription object.
Body
Object: subscription
Parameter
Data Type
Req?
Brief description
Location
subscriptionId
String
Yes
Returns the ID for the newly created subscription.
Body
expiresIn
Integer
No
An integer value that represents the time remaining in seconds in which the subscription will expire. When the subscription expires the developer server is expected to renew the subscription by invoking the Update Subscription Notification call.
Body
events
String Array
Yes
Specifies a filter for selecting the event types the application developer is interested in subscribing for notifications.
Valid values for ADTM :
- "ADTM_USAGE_CAP": ADTM usage threshold events
- "ADTM_SPEND_CAP": ADTM spend cap events
"ADTM_SESSION": ADTM On-Demand session status events
Body
callbackData
String
Yes
The piece of data that the DHS passed to the AT&T gateway while creating the subscription. If data was not passed during create subscription then an empty string value will be returned.
Body
The Update Notification Subscription operation can be used by an app to modify the properties of a previously created Notification Subscription. This operation also renews the Subscription and rests the expiresIn property.
The Update Notification Subscription operation will be limited to changing the details that were allowed during the Create Notification Subscription operation. Since this is a PUT operation the request body should be fully populated, however some of the values of fields which cannot be modified should be set to original values by the caller.
OAuth Scope
Scope: SESSIONS:ADTM
Resource URL
PUT https://api.att.com/notification/v2/channels/{channelId}/ subscriptions/{subscriptionId}
Request
PUT /notification/v2/channels/{channelId}/subscriptions/{subscriptionId} HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json content-type: application/json { "subscription": { "events": [ "ADTM_SPEND_CAP", "ADTM_USAGE_CAP", "ADTM_SESSION" ] , "callbackData" : "unique_user_id", "expiresIn": 16836 } }
Response
HTTP/1.1 200 OK content-type: application/json x-systemTransactionId: apptrans12345678 { "subscription": { "subscriptionId": "{subscriptionId}", "expiresIn": 86400 } }
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header.
Header
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
channelId
String
Yes
Specifies the unique Id of the Notification Channel in which the subscription is created.
URI Path
subscriptionId
String
Yes
Specifies the unique Id of the notification subscription.
URI Path
subscription
Subscription Object
Yes
Specifies subscription object.
Body
Object: subscription
Parameter
Data Type
Req?
Brief description
Location
expiresIn
Integer
No
An integer value that represents the time remaining in seconds in which the subscription will expire. When the subscription expires the developer server is expected to renew the subscription by invoking the Update Subscription Notification call.
Body
events
String Array
Yes
Specifies a filter for selecting the event types the application developer is interested in subscribing for notifications.
Valid values for ADTM :
- "ADTM_USAGE_CAP": ADTM usage threshold events
- "ADTM_SPEND_CAP": ADTM spend cap events
- "ADTM_SESSION": ADTM On-Demand session status events
Body
callbackData
String
Yes
The piece of data that the DHS passed to the AT&T gateway while creating the subscription. If data was not passed during create subscription then an empty string value will be returned.
Body
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
application/json
Note: If there is no entity body in a normal successful response, this parameter is still needed to specify the format in the case of an error response message.
Header
location
String
Yes
Returns the location of the newly created notification subscription.
Header
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
subscription
Subscription Object
Yes
Returns the subscription object.
Body
Object: subscription
Parameter
Data Type
Req?
Brief description
Location
subscriptionId
String
Yes
Returns the ID for the newly created subscription.
Body
expiresIn
Integer
No
An integer value that represents the time remaining in seconds in which the subscription will expire. When the subscription expires the developer server is expected to renew the subscription by invoking the Update Subscription Notification call.
Body
The Delete Notification Subscription operation allows a developer to delete a previously created subscription on a Notification Channel. All notifications will cease when the subscription is deleted. This operation uses client credential grant type
OAuth Scope
Scope: NOTIFICATIONCHANNEL | Model: Client Credential
Resource URL
DELETE https://api.att.com/notification/v2/channels/{channelId}/ subscriptions/{subscriptionId}
Request
DELETE /notification/v2/channels/{channelId}/subscriptions/{subscriptionId} HTTP/1.1 Host: api.att.com authorization: Bearer abcdef12345678 accept: application/json content-type: application/json
Response
HTTP/1.1 204 No Content Date: Thu, 04 Jun 2010 02:51:59 GMT x-systemTransactionId: apptrans12345678
Request Parameters
Parameter
Data Type
Req?
Brief description
Location
accept
String
No
Specifies the format of the body of the response. Valid values are:
- application/json
Header
authorizatiion
String
Yes
Specifies the authorization type and token. "Bearer" + OAuth Token – access_token. If the authorization header is missing, the system shall return an HTTP 400 Invalid Request message. If the token is invalid the system shall return an HTTP 401 Unauthorized message with a WWW-Authenticate HTTP header
Header
content-type
String
Yes
Specifies the type of content of the body of the entity. Must be set to one of the following values:
- application/json
Header
channelId
String
Yes
Specifies the unique Id of the Notification Channel in which the subscription is created.
URI Path
subscriptionId
String
Yes
Specifies the unique Id of the notification subscription.
URI Path
Response Parameters
Parameter
Data Type
Req?
Brief description
Location
x-systemTransactionId
String
No
This value returned by AT&T will help the developers to debug their applications while engaging with AT&T support.
Header
Sorry! Your session has expired.