SIMETRY Smart SIM Platform provides an application programming interface (API) that allows you to access and edit data from an external application. Using the API you can perform many of the same tasks you can handle through SIMETRY Smart SIM Platform’s web interface, including:
- Assigning a plan to an eSIM
- Enable and suspend data consumption
- Monitor data consumption, device status and rate plan status
- 1 Introduction
- 1.1 API Key
- 2 eSIM API
- 2.1 Get eSIMs
- 2.2 Data Cap API
- 2.3 Get Data Caps
- 2.4 Add Data Cap
- 2.5 Remove Data Cap
- 3 Change Plan API
- 3.1 List Plan
- 3.2 Change Plan
- 4 Disable / Enable eSIM API
- 4.1 Disable Data Consumption
- 4.2 Enable Data Consumption
- 5 Data Consumption API
- 5.1 Get CDR Data
- 5.2 Get Aggregated Data Consumption
- 5.3 Get Aggregated Plan Consumption
- 6 Send SMS
- 7 Meerkat
- 7.1 Assign Private IP
- 7.2 Assign Public IP
- 8 Notifications
- 8.1 AWS SQS Message
- 8.2 Notification Event Structure
- 8.3 Operation Result Notification
- 8.4 AWS sqs message
- 8.5 Notification Fvent Structure
Introduction
Every operation, e.g. collecting a list of items, executing plan change, enabling/disabling data consumption, requires a request ID i.e. a unique UUID (preferably 32 alpha-numeric unique value) and callback URL.
API call pushes requested operation to queue. After the operation is processed, its result can be fetched using operation result API call, by providing request ID. When the operation result is ready, callback URL will be invoked with prepended parameter “requestId”.
Example:
requestId: asdf5687efwef98765efasdfe8789512
Callback URL provided: http://notificationendpoint.com/anypath?optionalParameter1=a&requestId=asdf5687efwef98765efasdfe8789512
All API call definition can be found in our Swagger documentation: https://integrationapi.teal.global/swagger-ui.html
If operation is being processed and operation result API call is executed, HTTP 102 Processing API call will be returned.
Callback URL notification is mandatory parameter, but notification itself is not mandatory, to execute operation result API call.
API Key
API keys are located on the "Account" page of the Connectivity Marketplace dashboard.
eSIM API
Each eSIM can be assigned with one plan. Assigned plan can be fetched using eSIM API call, eSIM entry contains field “planUuid”, which corresponds to uuid of plan (can be fetched using plan API call).
eSIM entry contains:
- Device status
- WAITING (device is not polling)
- ONLINE (device is polling)
- STOPPED (device data consumption is suspended)
- Plan uuid – current assigned plan uuid value.
Get eSIMs
API Endpoint
HTTP GET https://integrationapi.teal.global/api/v1/esims
Example:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/esims?callbackUrl=https://customer.system.app/callback-endpoint&limit=3&requestId=requestid000000002' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' \ --header 'Content-Type: application/json' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000002" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000002' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apikey>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "id": 28xxx, "iccid": "8901990000000307xxx", "imsi": "234500024513xxx", "msisdn": "234500024513xxx", "eid": "89034011014200000000000000871xxx", "planId": 10066, "planUuid": "ddc51c077197454780b9ccc30b9efd18", "planName": "United States - AT&T Mobility", "planVolumeUnit": null, "planPrice": null, "suspended": false, "deviceName": "<deviceName>", "deviceStatus": "ONLINE", "planChangeStatus": "SUCCESS", "clientId": <clientId>, "clientName": "<clientName>", "clientUuid": "<clientUuid>", "deviceGroupName": "<deviceGroupName>", "clientChangeTimestamp": null, "profileChangeStatus": "TERMINATED", "flowType": "PLAN_CHANGE", "bootstrapIccid": "8901990000000307xxx", "bootstrapImsi": "234500024513xxx" }, { "id": 28xxx, "iccid": "8901990000000307xxx", "imsi": "234500024513xxx", "msisdn": "234500024513xxx", "eid": "89034011014200000000000000871xxx", "planId": 10210, "planUuid": "910207e0d0d242d780250243bfc86986", "planName": "United States - T-MO / AT&T / VZW / Sprint", "planVolumeUnit": null, "planPrice": null, "suspended": false, "deviceName": "<device name>", "deviceStatus": "ONLINE", "planChangeStatus": "SUCCESS", "clientId": <client id>, "clientName": "<client name>", "clientUuid": "<client uuid>", "deviceGroupName": "<device group name>", "clientChangeTimestamp": null, "profileChangeStatus": null, "flowType": "PLAN_CHANGE", "bootstrapIccid": "8901990000000307xxx", "bootstrapImsi": "234500024513xxx" }, { "id": 28xxx, "iccid": "8901990000000307xxx", "imsi": "234500024513xxx", "msisdn": "234500024513xxx", "eid": "89034011014200000000000000871xxx", "planId": 16010, "planUuid": "9d7f749019a84974b0b4381331401903", "planName": "USA 1GB Plan (AT&T, T-Mobile, Verizon)", "planVolumeUnit": null, "planPrice": null, "suspended": false, "deviceName": "Plains Internet Teltonika_884B", "deviceStatus": "WAITING", "planChangeStatus": "SUCCESS", "clientId": <client id>, "clientName": "<client name>", "clientUuid": "<client uuid>", "deviceGroupName": "<device group name>", "clientChangeTimestamp": null, "profileChangeStatus": null, "flowType": "PLAN_CHANGE", "bootstrapIccid": "8901990000000307xxx", "bootstrapImsi": "234500024513xxx" } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/esims?requestId=&offset=0&limit=3&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=&callbackUrl=https://customer.system.app/callback-endpoint&eid=&planUuid=&deviceName=&deviceGroupName=" }, "next": { "href": "http://integrationapi.teal.global/api/v1/esims?requestId=&offset=3&limit=3&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=&callbackUrl=https://customer.system.app/callback-endpoint&eid=&planUuid=&deviceName=&deviceGroupName=" }, "prev": { "href": "http://integrationapi.teal.global/api/v1/esims?requestId=&offset=0&limit=3&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=&callbackUrl=https://customer.system.app/callback-endpoint&eid=&planUuid=&deviceName=&deviceGroupName=" }, "info": { "href": "http://integrationapi.teal.global/api/v1/esims/info?requestId=&offset=0&limit=3&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=&callbackUrl=https://customer.system.app/callback-endpoint&eid=&planUuid=&deviceName=&deviceGroupName=" } } }Data Cap API
Data cap can be assigned to eSIM with defined threshold, which if reach, will execute data consumption suspension (data consumption will be disabled).
Data cap is configured in bytes and has a validity period, e.g. 1 month - meaning, that on every first day of the month, the data cap will be reset and the eSIM will be allowed to consume the predefined amount of data.
Currently, data cap is calculated from offline CDR files - meaning that data consumption is recorded when telco operator provides data consumption. Telco operators provide data consumption records with delay, and for that reason it is possible that eSIM will overuse some amount of data, before it will be disabled from data consumption.
Data cap API returns eSIM data cap configuration - total count is returned of eSIMs. If eSIM does not have data cap - it will be returned in the response without data cap values.
Data cap response also provides value in bytes (attribute name “usage”) - which provides current usage on data cap by eSIM.
Assigned data cap is also returned in Get eSIM API call.
Get Data Caps
API Endpoint
HTTP GET https://integrationapi.teal.global/api/v1/esims/data-cap
Example:
Request:
curl --location --request GET 'https://integrationapi.teal.global/api/v1/esims/data-cap?requestId=requestid000000104&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint' \--header 'ApiKey: <api secret>' \--header 'ApiSecret: <api key>' Response:
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000104", "_links": { "operationResult": { "href": "http://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000104" } }}API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000104' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "totalCount": 5393, "entries": [ { "uuid": null, "eid": "8903401101022000000000000000xxxx", "usage": null, "cap": null, "capped": false, "capResolutionType": null, "validityTime": null, "validityTimeUnit": null, "validityStartPeriod": null, "validityEndPeriod": null }, { "uuid": null, "eid": "8903401101022000000000000000xxxx", "usage": null, "cap": null, "capped": false, "capResolutionType": null, "validityTime": null, "validityTimeUnit": null, "validityStartPeriod": null, "validityEndPeriod": null } ], "_links": { "operationResult": { "href": "http://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000104" }, "self": { "href": "http://integrationapi.teal.global/api/v1/esims/data-cap?requestId=&offset=0&limit=2&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=https://customer.system.app/callback-endpoint&callbackUrl=&eid=&planUuid=&deviceName=&deviceGroupName=" }, "next": { "href": "http://integrationapi.teal.global/api/v1/esims/data-cap?requestId=&offset=2&limit=2&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=https://customer.system.app/callback-endpoint&callbackUrl=&eid=&planUuid=&deviceName=&deviceGroupName=" }, "prev": { "href": "http://integrationapi.teal.global/api/v1/esims/data-cap?requestId=&offset=0&limit=2&sort.eid=&sort.deviceName=&sort.deviceGroupName=&sort.clientChangeTimestamp=https://customer.system.app/callback-endpoint&callbackUrl=&eid=&planUuid=&deviceName=&deviceGroupName=" } }}Add Data Cap
HTTP POST https://integrationapi.teal.global/api/v1/esims/add-data-cap
Example
Request:
curl --location --request POST 'https://integrationapi.teal.global/api/v1/esims/add-data-cap?requestId=requestid000000101&callbackUrl=https://customer.system.app/callback-endpoint' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' \--header 'Content-Type: application/json' \--data-raw '{ "entries" : [ { "eid" : "8903401101022000000000000000xxxx", "validityTime" : "1", "validityTimeUnit" : "MONTH", "cap" : "15000000", "capResolutionType" : "SUSPEND_DATA" } ]}'Response:
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000101", "_links": { "operationResult": { "href": "http://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000101" } }}API Operation Result
Request:
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000101' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>'Response:
"success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "message": "", "errorCode": null, "errors": [], "eid": "8903401101022000000000000000xxx" } ], "_links": { "operationResult": { "href": "http://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000101" }, "self": { "href": "http://integrationapi.teal.global/api/v1/esims/add-data-cap?requestId=&callbackUrl=https://customer.system.app/callback-endpoint" } }}Remove Data Cap
API Endpoint:
HTTP POST https://integrationapi.teal.global/api/v1/esims/remove-data-cap
Example
Request:
curl --location --request POST 'https://integrationapi.teal.global/api/v1/esims/remove-data-cap?requestId=requestid000000105&callbackUrl=https://customer.system.app/callback-endpoint' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' \--header 'Content-Type: application/json' \--data-raw '{ "entries" : [ "8903401101022000000000000000xxx" ]}'Response:
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000105", "_links": { "operationResult": { "href": "http://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000105" } }}API Operation Result:
Request:
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000105' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' Response:
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "message": "", "errorCode": null, "errors": [], "eid": "8903401101022000000000000000xxxx" } ], "_links": { "operationResult": { "href": "http://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000105" }, "self": { "href": "http://integrationapi.teal.global/api/v1/esims/remove-data-cap?requestId=&callbackUrl=https://customer.system.app/callback-endpoint" } }}Change Plan API
Plan change operation assigns new plan to eSIM and initiates required SIMETRY platform operations. A plan defines rate and network coverage.
Plan change status can be monitored by fetching eSIM and checking planChangeStatus field, which can have the following values:
- IN_PROGRESS – Plan change operation is in progress.
- SUCCESS – Plan change operation finished.
- FAILED – Plan change operation failed → Please contact SIMETRY tech support@simetry.com
- TERMINATED – Plan change operation was terminated manually.
For plan change to be executed, plan uuid is required. Plan uuid can be fetched using Plan Listing API.
List Plan
API Endpoint
HTTP GET https://integrationapi.teal.global/api/v1/plans
Example:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/plans?requestId=requestid000000003&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000003" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000003' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "id": 10004, "name": "Argentina - Telecom Personal", "description": "Argentina - Telecom Personal", "price": 0.01, "volume": 1, "volumeUnit": "MB", "validityTime": 1, "validityTimeUnit": "YEAR", "maxReliability": 5, "reliability": 5, "networkTechType": "LTE", "networkTechTypeTitle": "LTE", "uuid": "d395d3642e594b9da372b40e2e5588ef", "profilePools": [ "GTI1GLOB1" ], "minUnitPriceBilling": false, "minUnitPrice": null, "minUnitVolume": null, "minUnitVolumeUnit": null }, { "id": 10005, "name": "Armenia - ArmenTel", "description": "Armenia - ArmenTel", "price": 0.01, "volume": 1, "volumeUnit": "MB", "validityTime": 1, "validityTimeUnit": "YEAR", "maxReliability": 5, "reliability": 5, "networkTechType": "LTE", "networkTechTypeTitle": "LTE", "uuid": "8930fb2c3e954f7096f33629ca65c67d", "profilePools": [ "TNP4GLOB1" ], "minUnitPriceBilling": false, "minUnitPrice": null, "minUnitVolume": null, "minUnitVolumeUnit": null } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/plans?requestId=&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&uuid=" }, "next": { "href": "http://integrationapi.teal.global/api/v1/plans?requestId=&offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&uuid=" }, "prev": { "href": "http://integrationapi.teal.global/api/v1/plans?requestId=&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&uuid=" } } } Change Plan
API Endpoint
HTTP POST https://integrationapi.teal.global/api/v1/plans
Example:
Request
curl --location --request POST 'https://integrationapi.teal.global/api/v1/esims/assign-plan?requestId=requestid000000004&callbackUrl=https://customer.system.app/callback-endpoint' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' \ --header 'Content-Type: application/json' \ --data-raw '{ "entries": [ { "eid" : "89034011014201000000000000000xxx", "planUuid" : "8930fb2c3e954f7096f33629ca65c67d" } ] }'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000004" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000004' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "eid": "89034011014201000000000000000xxx", "errorMessage": null } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/esims/assign-plan?requestId=&callbackUrl=https://customer.system.app/callback-endpoint" } } }
Disable / Enable eSIM API
eSIM data consumption can be disabled and enabled using integration API. Connectivity is controlled directly at carrier level. If eSIM is disabled, device will be disconnected and suspended from consuming any data, and polling notifications will not be transmitted.
eSIM deviceStatus field provides following values to track eSIM connectivity status:
- WAITING – Device is not polling / has no connectivity
- ONLINE – Device is polling / is online
- STOPPED – Device data consumption is disabled
Disable Data Consumption
API Endpoint
HTTP POST https://integrationapi.teal.global/api/v1/esims/disable
Example:
Request
curl --location --request POST 'https://integrationapi.teal.global/api/v1/esims/disable?requestId=requestid000000006&callbackUrl=https://customer.system.app/callback-endpoint' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' \ --header 'Content-Type: application/json' --data-raw '{ "entries" : ["89034011014201000000000000000xxx"] }'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000006" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000006' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "eid": "89034011014201000000000000000xxx", "errorMessage": null } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/esims/disable?requestId=&callbackUrl=https://customer.system.app/callback-endpoint" } } }Enable Data Consumption
API Endpoint
HTTP POST https://integrationapi.teal.global/api/v1/esims/enable
Example:
Request
curl --location --request POST 'https://integrationapi.teal.global/api/v1/esims/enable?requestId=requestid000000007&callbackUrl=https://customer.system.app/callback-endpoint' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' \ --header 'Content-Type: application/json' \ --data-raw '{ "entries" : ["89034011014201000000000000000xxx"] }'
Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000007" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000007' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>' Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "eid": "89034011014201000000000000000xxx", "errorMessage": null } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/esims/enable?requestId=&callbackUrl=https://customer.system.app/callback-endpoint" } } }
Data Consumption API
Data consumption is provided in the following formats:
- CDR data – CDR session logs.
- Aggregated data consumption.
- Aggregated plan consumption – data consumption grouped by consumed plan.
- Invoice preview - total data consumption and billing information for selected period.
- eSIM billing preview – data consumption and billing information for selected period for specified eSIMs.
Get CDR Data
CDR data represents data sessions. Data is not grouped or aggregated, CDR entries are returned as is.
API Endpoint
HTTP GET https://integrationapi.teal.global/api/v1/data-consumption
Example:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/data-consumption?offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&requestId=requestid000000008' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000008" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000008' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "id": 773xxx, "eid": "89034011010220000000000000217xxx", "operationalImsi": "234500024501xxx", "bootstrapIccid": "8901990000000017xxx", "startTime": "2020-06-09 14:01:52", "stopTime": "2020-06-09 14:02:35", "mccMnc": "310260", "pmn": "USAW6", "totalUsage": 1000, "cellId": "" }, { "id": 773xxx, "eid": "89034011010220000000000000217xxx", "operationalImsi": "234500024501xxx", "bootstrapIccid": "8901990000000017xxx", "startTime": "2020-06-09 13:58:52", "stopTime": "2020-06-09 13:59:15", "mccMnc": "310260", "pmn": "USAW6", "totalUsage": 1000, "cellId": "" } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/data-consumption?requestId=&offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&bootstrapIccid=&periodStart=&periodEnd=" }, "next": { "href": "http://integrationapi.teal.global/api/v1/data-consumption?requestId=&offset=4&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&bootstrapIccid=&periodStart=&periodEnd=" }, "prev": { "href": "http://integrationapi.teal.global/api/v1/data-consumption?requestId=&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&bootstrapIccid=&periodStart=&periodEnd=" } } }Get Aggregated Data Consumption
CDR data is aggregated per eID into several groups by period and aggregation type. Aggregation type is selected by request parameter “dataType”. The data is aggregated into the following groups:
dataType parameter value | Data |
DAILY | Summed consumption for eID per day |
MONTHLY | Summed consumption for eID per month |
DAILY_PROVIDER_NETWORK | Summed consumption for eID per day per unique network, on which eSIM consumed |
MONTHLY_PROVIDER_NETWORK | Summed consumption for eID per month per unique network, on which eSIM consumed |
API Endpoint
HTTP GET https://integrationapi.teal.global/api/v1/data-consumption/data
Example:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/data-consumption/data?offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&requestId=requestid000000009&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00&dataType=DAILY_PROVIDER_NETWORK' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000009" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000008' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "id": 216xxx, "eid": "89034011010220000000000000204xxx", "operationalImsi": "234500024500xxx", "type": "DAILY_PROVIDER_NETWORK", "period": "2021-01-01 00:00:00", "usage": 7978000, "mccMnc": "310260", "pmn": "USAW6" }, { "id": 216xxx, "eid": "89034011010220000000000000204xxx", "operationalImsi": "234500024500xxx", "type": "DAILY_PROVIDER_NETWORK", "period": "2021-01-01 00:00:00", "usage": 9739000, "mccMnc": "310260", "pmn": "USAW6" } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/data-consumption/data?requestId=&offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&dataType=DAILY_PROVIDER_NETWORK&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00" }, "next": { "href": "http://integrationapi.teal.global/api/v1/data-consumption/data?requestId=&offset=4&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&dataType=DAILY_PROVIDER_NETWORK&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00" }, "prev": { "href": "http://integrationapi.teal.global/api/v1/data-consumption/data?requestId=&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&dataType=DAILY_PROVIDER_NETWORK&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00" } } }Get aggregated plan consumption
CDR data is aggregated per eID per consumed plan, into several groups by period and aggregation type. Aggregation type is selected by request parameter “dataType”. The data is aggregated into the following groups:
dataType parameter value | Data |
DAILY | Summed consumption for eID per day per plan |
MONTHLY | Summed consumption for eID per month per plan |
DAILY_PROVIDER_NETWORK | Summed consumption for eID per day per plan per unique network, on which eSIM consumed |
MONTHLY_PROVIDER_NETWORK | Summed consumption for eID per month per plan per unique network, on which eSIM consumed |
API Endpoint
HTTP GET https://integrationapi.teal.global/api/v1/data-consumption/plan
Example:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/data-consumption/plan?offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&requestId=requestid000000010&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00&dataType=DAILY_PROVIDER_NETWORK' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "requestid000000010" }API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000010' \ --header 'ApiKey: <apikey>' \ --header 'ApiSecret: <apisecret>'Response
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "id": 206xxx, "eid": "89034011010220000000000000209xxx", "operationalImsi": "234500024501xxx", "type": "DAILY_PROVIDER_NETWORK", "period": "2021-01-01 00:00:00", "usage": 8453000, "mccMnc": "310410", "pmn": "USACG", "planUuid": "91e2d37aaf0b4d57993c5033e42d9f83" }, { "id": 206720, "eid": "89034011010220000000000000208xxx", "operationalImsi": "234500024501xxx", "type": "DAILY_PROVIDER_NETWORK", "period": "2021-01-01 00:00:00", "usage": 8609000, "mccMnc": "310260", "pmn": "USAW6", "planUuid": "0dd91298ca224c91b1d4fb19f4928782" } ], "_links": { "self": { "href": "http://integrationapi.teal.global/api/v1/data-consumption/plan?requestId=&offset=2&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&planUuid=&dataType=DAILY_PROVIDER_NETWORK&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00" }, "next": { "href": "http://integrationapi.teal.global/api/v1/data-consumption/plan?requestId=&offset=4&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&planUuid=&dataType=DAILY_PROVIDER_NETWORK&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00" }, "prev": { "href": "http://integrationapi.teal.global/api/v1/data-consumption/plan?requestId=&offset=0&limit=2&callbackUrl=https://customer.system.app/callback-endpoint&eid=&operationalImsi=&planUuid=&dataType=DAILY_PROVIDER_NETWORK&periodStart=2021-01-01%2000:00:00&periodEnd=2021-02-18%2000:00:00" } } }Send SMS
SIMETRY provides integration API to send SMS to current active eSIM profile - SMS is placed to telco operators' SMS gateway. SMS delivery reports are currently not available. If operation result returns success, it means that the SMS was queued in the operator's SMS gateway.
If more detailed configuration of SMS would be required, e.g. binary SMS, please contact SIMETRY support (support@simetry.com).
API Endpoint
HTTP POST https://integrationapi.teal.global/api/v1/sms
Example:
Request
curl --location --request POST 'https://integrationapi.teal.global/api/v1/sms?requestId=requestid000000013&callbackUrl=https://customer.system.app/callback-endpoint' --header 'ApiKey: <api key>' --header 'ApiSecret: <api secret>' --header 'Content-Type: application/json' --data-raw '{"entries": [ { "eid" : "8903401101022000000000000000xxxx", "messageType" : "TEXT", "message" : "Prod sms 20210610 1102", "from" : "37060873000" } ] }'Response
{"success": true,"message": "","errorCode": null,"errors": [],"requestId": "requestid000000013"}API Operation Result:
Request
curl --location --request GET 'https://integrationapi.teal.global/api/v1/operation-result?requestId=requestid000000013' --header 'ApiKey: <api key>' --header 'ApiSecret: <api secret>' Response
{"success": true,"message": "","errorCode": null,"errors": [],"entries": [{"success": true,"message": "Message delivery pending","errorCode": null,"errors": [],"eid": "8903401101022000000000000000xxxx"}],"_links": {"self": {"href": "http://integrationapi.teal.global/api/v1/sms?requestId=&callbackUrl=https://customer.system.app/callback-endpoint"}}}Meerkat
SIMETRY has special firewalls which allows traffic if IMSI is in rad_imsi table of Meerkat database. Traffic comes in, firewall checks APN and IMSI and then applies assigned private IP and public IP.
Assign private IP
You can have a private VPN to ensure a secure connection to your IoT devices. In that case you will order private IPs.
API Endpoint:
localhost:8083/api/v1/meerkat-vpn/assign-private-ip?requestId=meerkatapi0000003
Example:
Request:
curl --location --request POST 'localhost:8083/api/v1/meerkat-vpn/assign-private-ip?requestId=meerkatapi0000003' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' \--header 'Content-Type: application/json' \--data-raw '{ "entries": [ { "eid": "89034011010220000000000000003564", "clientUuid": "3a439a03ac294e779532c24a6c51639c", "rangeUuid": "jonguuid", "meerkatVpnRegion": "NORTH_AMERICA" } ]}'Response :
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "meerkatapi0000003", "_links": { "operationResult": { "href": "http://localhost:8083/api/v1/operation-result?requestId=meerkatapi0000003" } }}API Operation Result:
Request:
curl --location --request GET 'localhost:8083/api/v1/operation-result?requestId=meerkatapi0000003' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' \--header 'Content-Type: application/json' \--data-raw ''Response:
- When private IP is assigned successfully :
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "eid": "89034011010220000000000000003564", "errorMessage": "" } ], "_links": { "operationResult": { "href": "http://localhost:8083/api/v1/operation-result?requestId=meerkatapi0000003" }, "self": { "href": "http://localhost:8083/api/v1/meerkat-vpn/assign-private-ip?requestId=&callbackUrl=" } }}- When VPN range is not found:
{ "success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": false, "eid": "89034011010220000000000000003564", "errorMessage": "Meerkat vpn range not found." } ], "_links": { "operationResult": { "href": "http://localhost:8083/api/v1/operation-result?requestId=meerkatapi0000003" }, "self": { "href": "http://localhost:8083/api/v1/meerkat-vpn/assign-private-ip?requestId=&callbackUrl=" } }}- When there is some internal error in request processing:
{ "success": false, "message": "Unable to process api request", "errorCode": "G000001", "errors": [], "entries": [], "_links": { "operationResult": { "href": "http://localhost:8083/api/v1/operation-result?requestId=meerkatapi0000003" }, "self": { "href": "http://localhost:8083/api/v1/meerkat-vpn/assign-private-ip?requestId=&callbackUrl=" } }}Assign public IP
A device can be accessed over the public internet if they have a known public static IP. Every public IP is mapped to a private IP in Meerkat. The public IP needs to have an internal private IP in order to work, so every new public IP assignment automatically receives an internal private IP.
API Endpoint:
localhost:8083/api/v1/meerkat-vpn/assign-public-ip?requestId=meerkatapi0000004
Example:
Request:
curl --location --request POST 'localhost:8083/api/v1/meerkat-vpn/assign-public-ip?requestId=meerkatapi0000004' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' \--header 'Content-Type: application/json' \--data-raw '{ "entries": [ { "eid": "89034011010220000000000000003564", "clientUuid": "3a439a03ac294e779532c24a6c51639c", "rangeUuid": "jonguuid", "meerkatVpnRegion": "NORTH_AMERICA" } ]}'Response:
{ "success": true, "message": "", "errorCode": null, "errors": [], "requestId": "meerkatapi0000004", "_links": { "operationResult": { "href": "http://localhost:8083/api/v1/operation-result?requestId=meerkatapi0000004" } }}API Operation Result:
Request
curl --location --request GET 'localhost:8083/api/v1/operation-result?requestId=meerkatapi0000004' \--header 'ApiKey: <api key>' \--header 'ApiSecret: <api secret>' \--header 'Content-Type: application/json' \--data-raw Response:
- When public IP is assigned successfully:
"success": true, "message": "", "errorCode": null, "errors": [], "entries": [ { "success": true, "eid": "89034011010220000000000000003564", "errorMessage": "" } ], "_links": { "operationResult": { "href": "http://localhost:8083/api/v1/operation-result?requestId=meerkatapi0000004" }, "self": { "href": "http://localhost:8083/api/v1/meerkat-vpn/assign-public-ip?requestId=&callbackUrl=" } }}Notifications
SIMETRY Smart SIM Platform emits events, which are pushed to a notification queue. Notifications are pushed to Amazon Simple Queue Service (SQS) message queue.
AWS notification configuration can be found on the account page of the Dashboard. SIMETRY provides AWS access / secret keys and SQS queue to connect to.
Notification integration APIs, which are provided in https://integrationapi.teal.global/swagger-ui.html, are enabled per customer request and are used to handle cases, when SQS integration cannot be used or notifications are rarely checked.
AWS provides SDK for most of programming languages / frameworks:
https://github.com/awsdocs/aws-doc-sdk-examples
AWS SQS message
AWS SQS message format will be the following:
{ "Type": "Notification", "MessageId": "c9a88896-4628-5503-bcfb-d07a4bc76xxx", "TopicArn": "arn:aws:sns:us-east-2:404383143xxx:<customer name>-notification-topic-prod", "Message": "{\"dataId\":null,\"id\":\"60720bafe8d6e64269b87xxx\",\"clientId\":<clientId>,\"notificationType\":\"SYSTEM\",\"notificationSubType\":\"DEVICE_ONLINE\",\"title\":\"Device was marked as online\",\"message\":\"Device was marked as online\",\"createdAt\":\"2021-04-10 20:33:51\",\"readAt\":null,\"uuid\":\"5cf3c44414ee444ca8d0806175e74xxx\",\"eid\":\"89034011014200000000000001012xxx\",\"masterChipId\":<master chip id>,\"planId\":null,\"planUuid\":null,\"profileImsi\":null,\"profileIccid\":null,\"inactive\":false,\"operationUuid\":null}", "Timestamp": "2021-04-10T20:33:51.218Z", "SignatureVersion": "1", "Signature": "DB5f/CLrIErqrB/ZGEv+SQlRT2qQbFsZY7hvLCcQoL/Z/IObyZluJDpWYMYBAmOjfhI5IKfX/andK0tT4br3i2ZPoxTG4z86bTsX5l0TbqePYYc4hBnaaOkeSIozOGvC3pVFQNEVJ96/K1X+izVaMziM9L+7EpYlGDnhgLqYwRaZzi0RjHpks6cm13b9Fx0NSLRNJfV3oU6CrG7ihF/2WvFXvvLxQM/S4T7zyeYXuwLNerSJNw7cTU2ZNTVocLUDxxtFPMhKkyAjRz1w/IPEJfeeqonV2B8D2m1lm7OJxQSXWEEajwNbdvuXEbJ63a+z8A+LZev9ucb6d7UeI6nxxx==", "SigningCertURL": "https://sns.us-east-2.amazonaws.com/SimpleNotificationService-010a507c1833636cd94bdb98bd93xxxa.pem", "UnsubscribeURL": "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-2:404383143xxx:<customer name>-notification-topic-prod:aa17ff53-20a6-4c07-88df-01e0adbd5xxx" }AWS SQS message consists of envelope and “Message” field – SIMETRY notification event data.
Notification event structure
Field | Description |
uuid | Unique UUID |
notificationType | SYSTEM – eSIM event MESSAGE – SIMETRY notification message, e.g. notification regarding issues in service or time of planned service window |
notificationSubType | PLAN_CHANGE – Plan change was executed PROFILE_ACTIVATION – eSIM profile was activated PROFILE_DOWNLOAD – eSIM profile was downloaded PROFILE_REMOVE – eSIM profile was removed PROFILE_ROLLBACK – eSIM profile rollback was executed in eSIM platform DEVICE_ONLINE – Device connected on network – is online DEVICE_OFFLINE – Device disconnected from network (eSIM did not poll for a predefined amount of minutes) PROFILE_OPERATION_RESULT- eSIM profile operation result (allows to track fine grained events from platform profile lifecycle) |
title | Message title |
description | Notification event description |
eid | eSIM eID |
createdAt | Notification event creation time |
planUuid | Plan UUID will be filled if event was created by plan change operation |
profileImsi | Profile IMSI will be filled if event was created by profile change operation |
profileIccid | Profile ICCID will be filled if event was created by profile change operation |
Operation Result Notification
Integration api result notification can be delivered not only through callback_url, but also through sqs message queue.
After integration api operation result is ready, operation result event message is pushed to sqs message queue.
Aws notification configuration can be found in customer portal in “Account” page. SIMETRY provides aws access / secret keys and sqs queue to connect to.
Aws sqs message
Aws sqs message format will be following:
{
"Type" : "Notification",
"MessageId" : "caf79636-4e75-5fe7-8d16-cc4a6b1cce81",
"TopicArn" : "arn:aws:sns:us-east-2:404383143741:<account name>-api-notification-topic-prod",
"Message" : "{"requestId":"<operation request id>"}",
"Timestamp" : "2022-02-08T08:00:41.202Z",
"SignatureVersion" : "1",
"Signature" : "j+ThdNaCDem08XbVSI6wKbWCi7GdfY8Ig/hrKHCkbQLdrk7wWThjmq+7SqOBNopYGNDXlaKuhfEFU71QFiJoMSVvj1bHVMUBJl/rPOr2a0FArTim+b6wl6SrDZamLQewOCM2OWeKcnK6VBJAB1p5mPmS8zmTJPSd9iAodHQFUe2J/3fGBayJvbfBEM1jYyEHkZ1/EF9n3asWNROD+W2SdCyhoOeeKkjeLLlIhs0+nw0YpSdW8YU7noIfb1WcJ9KezbiQBgdn3mrPMIRYgWxMRGdYCT6u4Y5JyUiqYEnEqY0EsPrzmI/S4gFbdI8IWJLaagjYmAyQ2teM3WtaIyFfDw==",
"SigningCertURL" : "https://sns.us-east-2.amazonaws.com/SimpleNotificationService-7ff5318490ec183fbaddaa2a969abfda.pem",
"UnsubscribeURL" : "https://sns.us-east-2.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-2:404383143741:<account name>-api-notification-topic-prod:e452cc45-1eb0-4061-9726-69b6bdc0835f"
}
Aws sqs message consists of envelope and “Message” field – SIMETRY notification event data.
Notification event structure
Field | Description |
requestId | Operation request id |
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article