AT&T Developer
  • Sign In

AT&T Dynamic Traffic Management API

  • Tour
  • Docs

API Documentation

  • Introduction
  • REST Quick Start
  • OAuth
  • Operations
    • Get Subscriber Eligibility
    • Create Session
    • Get Session
    • Update Session
    • Delete Session
    • Get Session Usage Details
    • Create Channel
    • Get Channel
    • Delete Channel
    • Create Subscriptions
    • Get Subscriptions
    • Update Subscriptions
    • Delete Subscriptions
  • SDKs
  • FAQs
  • Errors

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

1

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.

2

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:

3

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.

Create Dynamic Traffic Session Call FlowApplicationApplicationAT&T API PlatformAT&T API Platform(1)POST /sessionManagement/v2/sessions(x-att-service:{service-name})(2)Verify request &access token(3)202 Accepted (sessionId,status)

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

Operations

Get Subscriber Eligibility

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.

Create Session

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.

Get Session

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.

Update Session

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"

Delete Session

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"

Get Session Usage Details

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

Create Notification Channel

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

Get Notification Channel

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

Delete Notification Channel

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

Create Notification Subscription

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

Get Notification Subscription

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

Update Notification Subscription

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

Delete Notification Subscription

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

Back To Top
  • ADDITIONAL RESOURCES
    • SDK
    • Errors
  • SUPPORT
    • Contact Us
    • FAQs
    • Twitter
  • AT&T Developer Program on Github
  • AT&T Developer Program on Facebook
  • AT&T Developer Program on Twitter
AT&T Logo

Terms of Use   Privacy Policy   Your Privacy Choices California Consumer Privacy Act (CCPA) Opt-Out Icon
©2025 AT&T Intellectual Property. All rights reserved

AT&T, the AT&T logo and all other AT&T marks contained herein are trademark of AT&T Intellectual Property and/or AT&T affiliated companies.

14100000
Session Expiring

Your session is about to expire in !

Stay Signed In
Session Expired

Sorry! Your session has expired.

Skip to content