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.
Base URLPurpose
https://api.aerframe.aeris.comAerFrame Web Service
  • Application Management
  • Notification Channel Management
  • Subscription Management
  • Network Services (Clear Registration and Get Local Dailable Number)
  • Submitting MT SMS Request
https://longpoll.aerframe.aeris.comLongpoll Service
  • Support only long poll requests to fetch MO SMS and MT SMS Delivery Info notifications
Table 1: AerFrame Base URLs

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
OperationRequest URIDescription
POSTregistration/v2/{accountId}/applicationsRegister a New Application
GETregistration/v2/{accountId}/applications/{appId}Get Registered Application
GETregistration/v2/{accountId}/applications/{appId}Get All Registered Applications
DELETEregistration/v2/{accountId}/applications/{appId}De-Register an Application
Table 2: AerFrame API Operations
NamePresenceDescription
applicationNameMandatoryA name that the client can use to identify the application.
applicationTagMandatoryA tag that clients may use to tag this application. AerFrame stores it as it is without modifying and is not used in any way.
descriptionMandatoryA description about the application that the client can use to brief the application and what it is used for.
apiKeyMandatoryGenerated by the AerFrame and provided in the response. This key is used for authentication in the queryParam of the request URL of all other AerFrame services.
apiKeyLifetimeOptionalAerFrame ignores this property. An apiKey once created is valid for lifetime unless application is explicitly deleted.
resourceUrlMandatoryGenerated by the AerFrame service and included in the response.
applicationShortNameMandatoryThe unique identifier of the application with in the given account.
Table 3: AerFrame Application Attributes

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.
OperationRequest URIDescription
POSTnotificationchannel/v2/{accountId}/channelsCreate New Notification Channel
GETnotificationchannel/v2/{accountId}/channels/{channelId}Get a Notification Channel
GETnotificationchannel/v2/{accountId}/channelsGet All Notification Channels
DELETEnotificationchannel/v2/{accountId}/channels/{channelId}Delete a Notification Channel
Table 4: Notification Channel Management Operations
NamePresenceDescription
clientCorrelatorOptionalA name that the client can use to identify the application.
applicationTagOptionalA tag that clients may use to tag this application. AerFrame stores it as it is without modifying and is not used in any way.
channelTypeMandatoryA description about the application that the client can use to brief the application and what it is used for.
channelDataMandatoryGenerated by the AerFrame and provided in the response. This key is used for authentication in the queryParam of the request URL of all other AerFrame services.
channelLifetimeOptionalAerFrame ignores this property. An apiKey once created is valid for lifetime unless application is explicitly deleted.
callbackUrlMandatoryGenerated by the AerFrame service and included in the response.
resourceUrlMandatoryThe unique identifier of the application with in the given account.
Table 5: AerFrame Notification Channel Attributes
NamePresenceDescription
channelURLMandatoryGenerated by AerFrame and provided in the response for LongPoll channel type.
maxNotificationsOptionalDefines the maximum number of notifications that may be delivered in a notification list. Default is 15. AerFrame will wait for these many notifications or 10 seconds whichever is earlier. Applications that need lower latency should explicitly set this value of a lower number.
typeOptionalAerFrame only supports "nc:LongPollingData".
Table 6: AerFrame Notification Channel Data

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.
OperationRequest URIDescription
POSTsmsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptionsCreate New Outbound (MT) SMS Delivery Info Subscription
GETsmsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions/{subscriptionId}Get a Specific Outbound Subscription
GETsmsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptionsGet All Outbound Subscriptions for a Given Profile
DELETEsmsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions/{subscriptionId}Delete a Specific Outbound Subscription
POSTsmsmessaging/v2/{accountId}/inbound/subscriptionsCreate New Inbound (MO) SMS Subscription
GETsmsmessaging/v2/{accountId}/inbound/subscriptions/{subscriptionId}Get a Specific Inbound Subscription
GETsmsmessaging/v2/{accountId}/inbound/subscriptionsGet All Inbound Subscriptions
DELETEsmsmessaging/v2/{accountId}/inbound/subscriptions/{subscriptionId}Delete a Specific Inbound Subscription
Table 7: Subscription Management API Operations
NamePresenceDescription
callbackReferenceMandatoryNotification Endpoint. AeFrame provides LongPoll service to receive notifications. Hence, the only supported callbackReference is the AerFrame-provided LongPoll Notification Channel. The Client must first create a Notification Channel and pass the callback URL from the Notification Channel here. Push notifications will be supported in the future.
filterCriteriaMandatoryMust specify ServiceProfile names as "SP:sp1,sp2,sp3" or "SP:*" to subscribe for all service profiles under the account.
clientCorrelatorOptionalA correlator that the client can use to tag subscription. Clients can use this to identify subscription and avoid duplicate subscriptions. AerFrame stores it as it is without modifying and is not used in any way.
resourceURLMandatoryGenerated by the AerFrame service and included in the response. The URL identifies the newly created resource.
linkOptionalNot used by AerFrame.
Table 8: AerFrame Outbound DeliveryInfoSubscription
NamePresenceDescription
callbackReferenceMandatoryNotification Endpoint. AeFrame provides LongPoll service to receive notifications. Hence, the only supported callbackReference is AerFrame-provided LongPoll Notification Channel. The Client must first create a notification channel and pass the callback URL from Notification Channel here. Push notifications will be supported in the future.
destinationAddressMandatoryThis is the applicationShortName that manages the subscription. AerFrame will use this only for Push Notification Service and ignores this for Long Polling.
criteriaMandatoryMust specify ServiceProfile names as "SP:sp1,sp2,sp3" or "SP:*" to subscribe for all service profiles under the account.
clientCorrelatorOptionalA correlator that the client can use to tag the subscription. Clients can use this to identify subscriptions and avoid duplicate subscriptions. AerFrame stores it as it is without modifying.
resourceURLOptionalGenerated by the AerFrame service and included in the response. The URL identifies the newly created resource.
linkOptionalNot used by AerFrame.
Table 9: AerFrame Inbound SMS Message Subscription
NameTypePresenceDescription
notifyURLURIMandatoryNotify Callback URL.
callbackDataStringOptionalThis is passed back in each notification to the client application. Applications use it for correlation purposes.
notificationFormatENUM (XML, JSON)OptionalAerFrame supports only JSON.
Table 10: AerFrame Subscription CallbackReference

SMS Request Operations sections

OperationRequest URIDescription
POST/smsmessaging/v2/{accountId}/outbound/{applicationShortName}/requestsSend Outbound (MT) SMS
GET/notificationchannel/v2/{accountId}/longpoll/{channelId}Get Inbound SMS and Outbound SMS Delivery Info Notifications
POST/smsmessaging/v2/{account}/acknowledgementAcknowledge Inbound SMS
Table 11: AerFrame SMS Request API Operations
NamePresenceDescription
addressMandatoryArray of destination addresses to send SMS to. This version of AerFrame accepts IMSI.
senderAddressMandatorySender address represent the application to which return message or delivery info may be sent. It should match the applicationShortName in the URL.
senderNameOptionalNot used by AerFrame.
chargingOptionalNot used by AerFrame.
receiptRequestOptionalNot used by AerFrame. AerFrame uses subscription to deliver the delivery info. If a subscription exists for the serviceProfile then all delivery info will be delivered to the notification channel associated with subscription.
outboundSMSTextMessageChoiceShould be used when sending text messages. AerFrame uses 7-bit encoding when delivering text messages to device. One of outboundSMSTextMessage or outboundSMSBinaryMessage must be present.
outboundSMSBinaryMessageChoiceShould be used when sending binary messages. AerFrame uses 7-bit/8-bit encoding when delivering binary messages to device. One of outboundSMSTextMessage or outboundSMSBinaryMessage must be present.
clientCorrelatorOptionalNot used by AerFrame.
resourceURLMandatoryGenerated by AerFrame and included in the response.
linkOptionalNot used by AerFrame.
deliveryInfoListOptionalNot used by AerFrame.
Table 12: AerFrame Outbound SMS Request Attributes
NamePresenceDescription
messageMandatoryShort text message content
Table 13: AerFrame OutboundSMSTextMessage
NamePresenceDescription
messageMandatoryShort binary message content. Base64 Encoded.
encodingSchemeMandatory"7-Bit" or "8-Bit" or "16-Bit"
Table 14: AerFrame OutboundSMSBinaryMessage
NamePresenceDescription
callbackDataOptionalCallback Data set in the inbound subscription is returned without modification.
inboundSMSMessageMandatoryInbound SMS Message received from device.
Table 15: AerFrame InboundSMSMessageNotification
NamePresenceDescription
dateTimeMandatoryTime the message was received from device.
messageMandatorySMS message as binary base 64 encoded message.
serviceProfileMandatoryService Profile of the device for which the message was received.
resourceURLOptionalPlaceholder to reference SMS message. Not used by AerFrame.
linkOptionalPlaceholder to reference related resources. Not used by AerFrame.
senderAddressMandatoryIMSI of device sending SMS.
destinationAddressMandatoryDestination Address of the message from the device.
messageIdMandatoryAerFrame generated and assigned unique message id.
encodingSchemeMandatory "7-Bit" or "8-Bit" or "16-Bit".
Table 16: AerFrame InboundSMSMessage
NamePresenceDescription
callbackDataMandatoryDevice identifier referred in OutboundSMSMessage. AerFrame uses IMSI.
deliveryInfoMandatoryOutbound SMS delivery info.
linkOptionalPlaceholder to reference related resources. Not used by AerFrame.
Table 17: AerFrame DeliveryInfoNotification
NamePresenceDescription
addressMandatoryDevice identifier referred in OutboundSMSMessage. AerFrame uses IMSI.
deliveryStatusMandatoryOne of following:
DeliveredToTerminal
DeliveryUncertain
DeliveryImpossible
MessageWaiting
DeliveredToNetwork
DeliveryNotificationNotSupported
descriptionOptionalMore details about the status.
linkMandatoryReference (Resource URL) to the send SMS request resource to which this deliveryInfo corresponds.
Table 18: AerFrame DeliveryInfo
NamePresenceDescription
messageMandatoryArray of AcknowledgeMessage
Table 19: AerFrame AcknowledgeMessageRequest
NamePresenceDescription
messageMandatoryArray of AcknowledgeMessage
Table 20: AerFrame AcknowledgeMessageResponse
NamePresenceDescription
messageIdMandatoryMessage Id of the message to be acknowledged.
messageTypeMandatoryInbound or Outbound.
serviceProfileMandatoryService Profile of the device for which the message was received.
successMandatorytrue or false. Receipt Status of the message. Specifies whether the message was received/processed successfully by the application.
acknowledgedMandatoryPopulated by AerFrame denoting the status of the acknowledgement of the message.
Table 21: AerFrame AcknowledgeMessage

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.

OperationURIDescription
DELETE/networkservices/v2/{accountId}/devices/{deviceIdType}/{deviceId}/registrationClear Registration for a Device:

Clears registration of device from the serving VLR and SGSN. DeviceIdType could IMSI or MSISDN. DeviceId is corresponding IMSI or MSISDN.

The Cancel Location is sent on a "best effort" basis. If the device's location is not known then a cancel location cannot be sent and the request is silently ignored. There is no result for a cancel location request.
GET/networkservices/v2/{accountId}/devices/{deviceIdType}/{deviceId}/localDialableNumberGet Local Dialable Number:

Obtain a temporary local dialable number for the device. DeviceIdType could IMSI or MSISDN. DeviceId is corresponding IMSI or MSISDN.
Table 22: AerFrame Network Service API Operations
NamePresenceDescription
dialableNumberMandatoryLocal dialable number that can be used to make MT Voice call.
numberNOAMandatoryNature of address of the returned dialable number.
numberNPMandatoryNumbering plan of the returned dialable number.
requestCompletedTimestampMandatoryTimestamp in milliseconds when the request was completed by the network.
validForSecondsMandatoryApproximate time in seconds for which the dialable number is valid.
requestIdMandatoryReference to the request Id. Used internally by AerFrame. Can be used as reference in support tickets.
Table 23: AerFrame Network Service API LocalDailableNumberResponse

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:

NamePresenceDescription
LinkOptionalList of resources that are related to the error. Not used by AerFrame.
serviceExceptionOptionalCaptures AerFrame service and request validation exception (e.g. Device not found).

Either serviceException or policyException will be present.
policyExceptionOptionalCaptures AerFrame policy/business rule violations.

Either serviceException or policyException will be present.
Table 24: AerFrame Request Errors

This table describes the Service / Policy Exceptions schema:

NamePresenceDescription
messageIdMandatoryError code (See section Service and Policy Exception Code for full list)
textMandatoryError text with variable placeholders
variablesOptionalList of values matching the number of placeholders in text
Table 25: AerFrame Service and Policy Exceptions

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

ValueError
-1Gsmmap pack failed
-2Gsmmap validation failed
-3Gsmmap submit failed
-4Gsmmap timeout
-5Gsmmap abort
-6Gsmmap reject
-7Gsmmap No Appropriate Stack Connection Available
-8Device is unreachable
-9Device location is unknown
-10RTTL expired
Table 26: AerFrame Error Codes