AerFrame – Device Communication and Control API

POST

registration/v2/{accountId}/applications

Register a New Application.

GET

registration/v2/{accountId}/applications/{appId}

Get Registered Application.

GET

registration/v2/{accountId}/applications/{appId}

Get All Registered Applications.

DELETE

registration/v2/{accountId}/applications/{appId}

De-Register an Application.

applicationName

Mandatory

A name that the client can use to identify the application.

applicationTag

Mandatory

A tag that clients may use to tag this application. AerFrame stores it as it is without modifying and is not used in any way.

description

Mandatory

A description about the application that the client can use to brief the application and what it is used for.

apiKey

Mandatory

Generated 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.

apiKeyLifetime

Optional

AerFrame ignores this property. An apiKey once created is valid for lifetime unless application is explicitly deleted.

resourceUrl

Mandatory

Generated by the AerFrame service and included in the response.

applicationShortName

Mandatory

The unique identifier of the application with in the given account.

POST

notificationchannel/v2/{accountId}/channels

Create New Notification Channel.

GET

notificationchannel/v2/{accountId}/channels/{channelId}

Get a Notification Channel.

GET

notificationchannel/v2/{accountId}/channels

Get All Notification Channels.

DELETE

notificationchannel/v2/{accountId}/channels/{channelId}

Delete a Notification Channel.

clientCorrelator

Optional

A name that the client can use to identify the application.

applicationTag

Optional

A tag that clients may use to tag this application. AerFrame stores it as it is without modifying and is not used in any way.

channelType

Mandatory

A description about the application that the client can use to brief the application and what it is used for.

channelData

Mandatory

Generated 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.

channelLifetime

Optional

AerFrame ignores this property. An apiKey once created is valid for lifetime unless application is explicitly deleted.

callbackUrl

Mandatory

Generated by the AerFrame service and included in the response.

resourceUrl

Mandatory

The unique identifier of the application with in the given account.

channelURL

Mandatory

Generated by AerFrame and provided in the response for LongPoll channel type.

maxNotifications

Optional

Defines 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.

type

Optional

AerFrame only supports "nc:LongPollingData".

POST

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions

Create New Outbound (MT) SMS Delivery Info Subscription.

GET

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions/{subscriptionId}

Get a Specific Outbound Subscription

GET

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions

Get All Outbound Subscriptions for a Given Profile.

DELETE

smsmessaging/v2/{accountId}/outbound/{applicationShortName}/subscriptions/{subscriptionId}

Delete a Specific Outbound Subscription.

POST

smsmessaging/v2/{accountId}/inbound/subscriptions

Create New Inbound (MO) SMS Subscription.

GET

smsmessaging/v2/{accountId}/inbound/subscriptions/{subscriptionId}

Get a Specific Inbound Subscription.

GET

smsmessaging/v2/{accountId}/inbound/subscriptions

Get All Inbound Subscriptions.

DELETE

smsmessaging/v2/{accountId}/inbound/subscriptions/{subscriptionId}

Delete a Specific Inbound Subscription.

callbackReference

Mandatory

Notification 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.

filterCriteria

Mandatory

Must specify ServiceProfile names as "SP:sp1,sp2,sp3" or "SP:*" to subscribe for all service profiles under the account.

clientCorrelator

Optional

A 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.

resourceURL

Mandatory

Generated by the AerFrame service and included in the response. The URL identifies the newly created resource.

link

Optional

Not used by AerFrame.

callbackReference

Mandatory

Notification 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.

destinationAddress

Mandatory

This is the applicationShortName that manages the subscription. AerFrame will use this only for Push Notification Service and ignores this for Long Polling.

criteria

Mandatory

Must specify ServiceProfile names as "SP:sp1,sp2,sp3" or "SP:*" to subscribe for all service profiles under the account.

clientCorrelator

Optional

A 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.

resourceURL

Optional

Generated by the AerFrame service and included in the response. The URL identifies the newly created resource.

link

Optional

Not used by AerFrame.

notifyURL

URI

Mandatory

Notify Callback URL.

callbackData

String

Optional

This is passed back in each notification to the client application. Applications use it for correlation purposes.

notificationFormat

ENUM (XML, JSON)

Optional

AerFrame supports only JSON.

POST

/smsmessaging/v2/{accountId}/outbound/{applicationShortName}/requests

Send Outbound (MT) SMS

GET

/notificationchannel/v2/{accountId}/longpoll/{channelId}

Get Inbound SMS and Outbound SMS Delivery Info Notifications

POST

/smsmessaging/v2/{account}/acknowledgement

Acknowledge Inbound SMS

address

Mandatory

Array of destination addresses to send SMS to. This version of AerFrame accepts IMSI. The array can contain up to 100 addresses.

Note: If you are sending an SMS to an eSIM, you must first retrieve the IMSI of the active profile on the eSIM. To retrieve the IMSI, use the AerAdmin API: Single Operation - Get Device Details (Non-Structured Response), and specify the EID as the identifier. The response payload returns the ICCID, IMSI, and MSISDN of the active profile.

senderAddress

Mandatory

Sender address represent the application to which return message or delivery info may be sent. It should match the applicationShortName in the URL.

senderName

Optional

Not used by AerFrame.

charging

Optional

Not used by AerFrame.

receiptRequest

Optional

Not 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.

outboundSMSTextMessage

Choice

Should 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.

outboundSMSBinaryMessage

Choice

Should 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.

clientCorrelator

Optional

Not used by AerFrame.

Note that this parameter is only honored if the destination device is set for carrier-delivered MT-SM or a Global SIM device whose service code is configured for the store and forward service; otherwise, this parameter is ignored.

Setting a large value of ttlInSeconds for a device that is offline will result in the final status (Delivered to Terminal or failed) notification not available until the ttlInSeconds period has elapsed.

resourceURL

Mandatory

Generated by AerFrame and included in the response.

link

Optional

Not used by AerFrame.

deliveryInfoList

Optional

Not used by AerFrame.

message

Mandatory

Short text message content. AerFrame does not accept empty messages.

The message text can have characters in ASCII, some from ISO-8859-1, and Unicode characters. However, the characters supported in the GSM7 basic and extended characters (as defined in the 3GPP TS 23.038 standard) set gets delivered to the device.

The characters that are not translatable into GSM7 are replaced by a space character.

The maximum length of the message field content is 160 characters.

NOTES:

The GSM7 character set uses different values for some of the ASCII characters and translates the input ASCII characters to their GSM7 equivalent characters.

Some GSM7 Extension characters are represented as two characters. While converting these extension characters, an <ESCAPE> character (value of 0x1b) is inserted before the actual GSM7 Extension character.Therefore, for each extension characters used in the message text, the maximum length of the message gets be reduced by one (since the <ESCAPE> character uses a character position). These Extension characters are:

message

Mandatory

encodingScheme

Mandatory

However, the values AerFrame accepts as encoding schemes don't map exactly to the values the mobile terminal receives:

Therefore, if you send the 16-Bit binary data to your devices (not having the Aeris Global SIM), the devices will see or receive the data coding as UCS-2.

callbackData

Optional

Callback Data set in the inbound subscription is returned without modification.

inboundSMSMessage

Mandatory

Inbound SMS Message received from device.

destinationAddress

Mandatory

senderAddress

Mandatory

IMSI of device sending SMS.

serviceProfile

Mandatory

Service Profile of the device for which the message was received.

message

Mandatory

SMS message as binary base 64 encoded message. AerFrame does not accept empty messages.

The interpretation of the message after decoding from base64 depends on the value of the encodingScheme:

NOTE:

The use of the Euro-Currency-sign ("€") should be avoided in 7-Bit MO-SM. There is no ISO-8859-1 character value for the Euro-Currency-sign. (The ISO-8859-1 standard was created before the Euro currency was created).

link

Optional

Placeholder to reference related resources. Not used by AerFrame.

messageId

Mandatory

AerFrame generated and assigned unique message id.

callbackData

Mandatory

Callback Data set in the outbound SMS delivery info subscription is returned without modification,

deliveryInfo

Mandatory

Outbound SMS delivery info.

link

Optional

Placeholder to reference related resources. Not used by AerFrame.

address

Mandatory

Device identifier referred in OutboundSMSMessage. AerFrame uses IMSI.

deliveryStatus

Mandatory

Defines the SMS delivery status, which can be one of following:

NOTE:

A final status means that this is the final DeliveryInfo status for this particular message. An interim status indicates that additional DeliveryInfo status will be provided for this particular message later.

description

Optional

More details about the status.

link

Mandatory

Reference (Resource URL) to the send SMS request resource to which this deliveryInfo corresponds.

message

Mandatory

Array of AcknowledgeMessage.

message

Mandatory

Array of AcknowledgeMessage.

messageId

Mandatory

Message Id of the message to be acknowledged.

messageType

Mandatory

Inbound or Outbound.

serviceProfile

Mandatory

Service Profile of the device for which the message was received.

success

Mandatory

true or false. Receipt Status of the message. Specifies whether the message was received/processed successfully by the application.

acknowledged

Mandatory

Populated by AerFrame denoting the status of the acknowledgement of the message.

DELETE

/networkservices/v2/{accountId}/devices/ {deviceIdType}/{deviceId}/registration

Clear Registration for a Device: Clears registration of device from the serving VLR and SGSN. DeviceIdType could be IMSI or MSISDN. DeviceId is the 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}/localDialableNumber

Get Local Dialable Number: Obtain a temporary local dialable number for the device. DeviceIdType could be IMSI or MSISDN. DeviceId is the corresponding IMSI or MSISDN.

This API returns the real-time information about the device network location.

NOTE:

• We recommend that you not exceed 1 request every 30 minutes per device.
• Making more frequent location requests per device could result in timeouts.

dialableNumber

Mandatory

Local dialable number that can be used to make MT Voice call.

numberNOA

Mandatory

Nature of address of the returned dialable number.

numberNP

Mandatory

Numbering plan of the returned dialable number.

requestCompletedTimestamp

Mandatory

Timestamp in milliseconds when the request was completed by the network.

validForSeconds

Mandatory

Approximate time in seconds for which the dialable number is valid.

requestId

Mandatory

Reference to the request Id. Used internally by AerFrame. Can be used as reference in support tickets.

responseType

Mandatory

Always returns as 'Cell ID' because this API is intended to retrieve the cell ID only.

mcc

Mandatory

Defines the Mobile Country Code (MCC) to identify the country of the device location. For example, 404 and 405 represent India, 310, 311, 312, 313, 314 and 316 represent USA, and so on.

mnc

Mandatory

Defines the Mobile Network Code (MNC) to identify the mobile operator in the MCC. See Cell Tower Locations below for additional details.

lac

Mandatory

Defines the Location Area Code (LAC) which is the unique identifier of the current location area. This LAC is a group of base stations that are used together to optimize signalling.

cellId

Mandatory

Defines the unique identifier of the Base Transceiver Station (BTS) or sector of a BTS within a LAC.

The Cell ID can be zero because it does not depend on the data returned from the last known switch. If the device is registered with switch A and then turned off and moved to another location or country and has not yet registered, then switch A is still the last known switch but the API returns no location because the device is no longer registered at that switch.

To keep getting updated Cell ID, it is recommend that you execute the API on regular intervals to have updated information of the Cell ID.

locationTimestamp

Optional

If not NULL or non-zero, then this is the timestamp when the location was received.This is non-NULL and non-zero if there is a location for this device.

Defines the age of location information in Minutes corresponding to how long ago the location information was retrieved from the network. Returns NULL or Zero if no location information is available.

Returns the CS state, which can be one of the following:

• 0 = assumedIdle
• 1 = camelBusy
• 2 = netDetNotReachable
• 3 = notProvidedFromVLR

Reference to the request Id. Used internally by AerFrame. Clients can use it as reference in support tickets.

Returns the switch type CS (Circuit Switch) or PS (Packet Switch) to represent the location result. Since this API works only on CS (Circuit Switch), this field always return CS as its value.

Returns 7 always to represent the destination type value, where 7 represents VLR (circuit switched PSI).

POST

/s-tap

This API sends a batch of one or more shoulder tap messages. (This is the same interface to send one or many shoulder taps; the same IMSI device can appear multiple times in the array of messages in a batch.)

If the same device is in the batch multiple times, each shoulder tap for that device is processed independently from the others.

The parameter names starting with “batch” apply to the entire batch. If an individual shoulder tap does not specify a value for the corresponding parameter, the batch value will be used. The request will be rejected if a batch parameter is not specified and an individual required shoulder tap parameter is not specified.

This API cancels a shoulder tap request.

The type is one of:

• request: This cancels an shoulder tap with the specified reqId.
• imsi: This cancels all shoulder taps for the device with the IMSI given as the reqId parameter.

If there is an error (not HTTP status 200), no response body is returned.

For an individual shoulder tap cancellation (by request ID), the returned reqIdList has only a single element in a successful cancellation. There is no response body for HTTP status values >= 400.

For cancellation by device ID, if there were no pending shoulder taps for that device, the HTTP status will be 404.

If the parameter is omitted, then a default of 72 hours is used. 72 hours is 259,200 seconds.

payloadType is either “ASCII” or “BASE64”. It defines how the payload parameter is to be interpreted.

If ASCII, then only printable ASCII characters (including space, CR, and LF) are in the payload.

If BASE64, then the payload must be in BASE64 format (RFC4648).

In either case, the payload is delivered in binary form in the UDP0 delivery mechanism. (BASE64 payloads are converted to binary, and ASCII payloads are passed through without conversion.)

If payloadType is neither “ASCII” nor “BASE64”, the individual shoulder tap is rejected.

If the payloadType is not present, then the batchPayloadType will be used.

If both the payloadType and the batchPayloadType are not present and a payload is present, then the message will be rejected.

If the payload is omitted or is an empty string, then the payloadType and batchPayloadType are not required.

The payload parameter represents the payload for a particular shoulder tap. The maximum payload length is 140 bytes.

If the payload is not present, then the batchPayload will be used.

If the payload is not present (or is an empty string) and the batchPayload is not present (or is an empty string), then the shoulder tap will contain a zero length payload.

Set the value of expires to 0 to make one attempt at a shoulder tap.

If it is greater than zero, it represents the time in seconds from request submission to when it expires.

If expires is less than zero, the individual shoulder tap is rejected.

If the parameter is omitted, then a default of 72 hours is used. 72 hours is 259,200 seconds.

If expires is greater than the maximum value (72 hours or 259,200 seconds), the shoulder tap message is rejected.

The only supported delivery mechanism is “UDP0”.

If the parameter is omitted, then “UDP0” is used as the default.

If deliveryMechanism is not “UDP0”, the individual shoulder tap is rejected.

If the optional deliveryPort parameter is omitted, then a value of 23747 is used as the default.

If the deliveryPort parameter is present, it must be greater than or equal to 1025 and less than or equal to 65535.

If deliveryPort is outside of that range, the individual shoulder tap is rejected.

This parameter is used to help with scheduling the shoulder tap. The powerSleepInterval is the time in seconds that the device is asleep (not reachable). Its value depends on the powerMode:

• PSM: the difference in values (in seconds) of 3GPP timers T3412 - T3324 (the TAU Period less the Active Timer).

• eDRX: The eDRX cycle (TeDrx) converted and rounded to seconds.

If powerSleepInterval is specified, it must be greater than or equal to zero.

If it is less than zero, the individual shoulder tap is rejected.

The mimimum value is 1.

If the powerAwakeInterval field is specified for a message, it must be greater than zero.

If it is less than or equal to zero, the individual shoulder tap is rejected.

The response has a list of the reqIds that were cancelled.

HTTP Status for any cancellation method:

• 400: bad request type (it needs to be one of “request” or “imsi”)

HTTP Status for a device ID shoulder tap cancellation:

• 200: OK. shoulder tap(s) cancelled. There will be zero or more reqIds in the response.
• 404: Device not found, or no shoulder taps were cancelled (no response body).
• 504: Internal problem: STS service did not respond before timeout.

Link

Optional

List of resources that are related to the error. Not used by AerFrame.

serviceException

Optional

Captures AerFrame service and request validation exception (e.g. Device not found). Either serviceException or policyException will be present.

policyException

Optional

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

messageId

Mandatory

Error code (See section Service and Policy Exception Code for full list).

text

Mandatory

Error text with variable placeholders.

variables

Optional

List of values matching the number of placeholders in text.

RTTL expired: The Relative-Time-To-Live of the message expired before it could be delivered.