What’s here?

This page describes the full set of AerFrame™ APIs. A hands-on tutorial is available at Send / receive SMS with AerFrame API.

Summary

AerFrame Short Message Service (SMS) APIs provide next-generation SMS messaging. AerFrame is designed for high performance and improved flexibility, allowing for fast and efficient data transmission to and from devices across the Aeris network.
Supported Operations
  • Send MT-SMS
  • Receive MT-SMS Delivery Notifications
  • Receive MO-SMS
  • Acknowledge MO-SMS Receipt
Features & Benefits
  • The SMS API is based on the OMA-DM standard SMS API
  • All AerFrame services are simple RESTful interfaces for rapid and simplified development
  • All AerFrame services are securely protected by API keys under customer control
  • The API for resetting network registration can be a powerful tool for resolving device connectivity issues
  • The API for getting a local dial-able number allows customers to deploy devices securely with non-dial-able numbers but still reach them when needed

API Overview sections

AerFrame includes the following set of APIs:

  • SMS Messaging API – derived from OMA Restful Short Messaging API. The outbound (MT) SMS delivery info and inbound (MO) SMS are delivered to applications over Notification Channels.
  • Notification Channel Management API – derived from OMA Notification Channel API. To receive MO SMS and delivery info for the MT SMS, applications must register themselves and setup a notification channel. All messages are delivered over Notification Channel. This version of AerFrame supports only the LongPoll Notification Channel.
  • The Network Service API – provides access to operations like Clear Registration and Get Local Dialable Number.

API Request, Headers and Parameters sections

  • AerFrame APIs are available only over HTTPS
  • Each API access must include the appropriate API Key in the request URL as shown in examples. The parameter name is “apiKey”
  • All API must include Content-Type header with value application/json

Base URLs

The URL addresses for the production services are shown in Table 1, “AerFrame Base URLs”. Access to the AerFrame service is restricted to Customers using Static IP addresses and a Virtual Private Network (VPN) connection or over Leased Lines—information on these options is available at the Aeris AerPort website. [table id=33 /]

API Client Authentication

AerFrame uses API Keys to authenticate clients and applications. Each request must include the API Key as a query parameter in the URL. The API Key uniquely identifies an account and provides the account context to the APIs. The Service Profile Name can then be used to further classify multiple applications belonging to an account.

There are two (2) sets of API keys:

  • Account API Key – When an account is registered for the AerFrame API, it is assigned a unique API Key. This API key can be used to perform all operations except subscription management. Subscriptions belong to applications and are managed by applications.
  • Application API Key – When an application is registered under an account, it is assigned a unique API Key. This API key can be used to perform all operations except application management.

API Key / Account ID

API Keys are unique and secret. They must be saved securely and should be shared with authorized users or apps only. To obtain your Account ID and API Key, refer to the Send / receive SMS with AerFrame API section.

Open Mobile Alliance Specification for SMS APIs

The AerFrame service interface is derived from the Open Mobile Alliance (OMA) Specification for SMS APIs (OMA-TS-REST_NetAPI_ShortMessaging-V1_0-20130219-C.pdf). The OMA RESTful Network API for Short Messaging V1.0 is a re-publication of the ParlayREST ShortMessaging API V 1.1 [ParlayREST_SMS] and is part of the suite of OMA RESTful Network APIs. Additionally, the latest version (v1.2.3) of the GSMA OneAPI SMS API is a subset of the OMA SMS API and uses the same resource structure and datatypes as defined in the OMA API Specification (http://www.gsma.com/oneapi/sms-restful-netapi).

Application Management Operations sections

  • AerFrame APIs are available only over HTTPS
  • Each API access must include the appropriate API Key in the request URL as shown in examples. The parameter name is “apiKey”
  • All APIs must include Content-Type header with value application/json
[table id=45 /] [table id=46 /]

Notification Channel Management Operations sections

There are up to two (2) Notification Channels available per application, with up to ten (10) total Notification Channels available per account. Each message will live for seven (7) days in the Notification Channel. [table id=47 /] [table id=48 /] [table id=49 /]

Subscription Management Operations sections

To get Inbound SMS and Outbound SMS delivery information, applications need to subscribe for notifications. If there is no corresponding subscription for inbound SMS messages they are held for seventy-two (72) hours with one (1) retry every twenty-four (24) hours to check if a valid subscription exist. After seventy-two (72) hours the messages are dropped. If there is no corresponding subscription for outbound SMS delivery info then they are dropped immediately. [table id=50 /] [table id=51 /] [table id=52 /] [table id=53 /]

SMS Request Operations sections

[table id=54 /] [table id=55 /] [table id=56 /] [table id=57 /] [table id=58 /] [table id=59 /] [table id=60 /] [table id=61 /] [table id=62 /] [table id=63 /] [table id=64 /]

Network Service API Operations sections

AerFrame Network Service API is a set of APIs to access core network features like Clear Registration and Get Local Dialable Number.

[table id=65 /] [table id=66 /]

Service / Policy Exception Codes and Messages sections

  • AerFrame 2.1 APIs use standard HTTP Status Codes to convey success or failure response
  • API response content, if any, is of type application/json

This table describes the Request Errors schema:

[table id=42 /]

This table describes the Service / Policy Exceptions schema:

[table id=43 /]

Sending a message to an invalid device id returns this response:

aerframe_invalid_device_response

Service Exceptions

SVC0001 = A service error occurred. Error code is {0}.

SVC0002 = Invalid input value for message part {0}.

SVC0003 = Invalid input value for message part {0}, valid values are {1}.

SVC0004 = No valid addresses provided in message part {0}.

SVC0005 = Correlator {0} specified in message part {1} is a duplicate.

SVC0006 = Group {0} in message part {1} is not a valid group.

SVC0007 = Invalid charging information.

SVC0008 = Overlapped Criteria {0}.

SVC0280 = Message too long. Maximum length is {0} characters.

SVC0281 = Data format not recognized for message part {0}.

SVC0283 = Delivery Receipt Notification not supported.

SVC0400 = Failed to submit Clear Registration for {0}.

SVC0401 = Service Error: Failure code {0}, Failure Message {1}.

SVC0402 = Service timed out. Please try again.

SVC1000 = No resources.

SVC2000 = The following service error occurred: {0}. Error code is {1}.

Policy Exceptions

POL0001 = A policy error occurred. Error code is {0}.

POL0002 = Privacy verification failed for address {0}, request is refused.

POL0003 = Too many addresses specified in message part {0}.

POL0004 = Unlimited notification request not supported.

POL0005 = Too many notifications requested.

POL0006 = Group specified in message part {0} not allowed.

POL0007 = Nested group specified in message part {0} not allowed.

POL0008 = Charging is not supported.

POL0009 = Invalid frequency requested.

POL0010 = Requested information unavailable as the retention time interval has expired.

POL0011 = Media type not supported.

POL0012 = Too many description entries specified in message part {0}.

POL0013 = Duplicated addresses.

POL1009 = User has not been provisioned for {0}.

POL1010 = User has been suspended from {0}.

POL1016 = File size exceeds the limit {0}.

POL1019 = Binary SMS is not allowed.

POL1020 = MaxBatchSize exceeded. The maximum allowed maxBatchSize is {0}.

POL2000 = The following policy error occurred: {0}. Error code is {1}.

AerFrame Error Codes sections

[table id=44 /]