Skip to main content
API docs by Redocly

IoT Portal APIs (v2.2)

Download OpenAPI specification:Download

Introduction

The purpose of the IoT Portal API is for external systems to integrate with the platform to automate operations that would otherwise be performed manually (e.g., active SIM orchange rate plan).

This page includes the specification and operations of the API, with examples where relevant.The documentation is interactive so you may perform operations directly on the API documentation andsee the responses.

Scope

The following operations are in the scope of the API (but some may not yet be available in the latest version):

  • Account Management;
  • Billing;
  • SIM usage and lifecycle management;
  • Attributes and Tags;
  • Sending SMS;
  • Rules;
  • Reports;
  • Notifications;
  • Audit Trail;

Specification

This is a REST-based API that relies heavily on JSON. Below is a list of the relevant characteristics of the API.

URIs

The root of the API is at https://iot.truphone.com/api/. Each API "operation" has an URI (e.g.,/api/v2.0/sims/) and may include a reference to a specific resources (e.g.,/api/v2.0/sims/12345/). Only URIs that finish with forward-slash are valid.

The name of the resources in the URI is always plural. If resources or actions need to be represented with two or more words,all the words will be lower case and separated by underscore (e.g., /api/v2.0/sims/send_sms/), instead of dash or camelCase.

URIs may have parameters for the purpose of filtering or ordering (see below).

Versioning

URIs are prefixed with a specific version. The URI without version is an alias to the latest version of the API.Below are examples of valid URI formats:

/api/resources/
/api/v1.0/resources/
/api/v1.1/resources/
/api/v2.0/resources/

Minor versions are backwards compatible (e.g., just adding a new operation or a new attribute to a response).Major versions may not be backwards compatible. We suggest you work with the latest version

We don't currently have a deprecation policy so all the versions of the API will continue to be supported untilfurther notice.

Methods

Requests must use the appropriated HTTP request method. Below is the list of methods:

MethodDescription
GETReturn objects or data
POSTPerform an action (e.g., change status or send SMS)
DELETEDelete a related resource(s) (e.g., delete attributes)
PATCHUpdating an existing resource(s) (e.g., change SIM Card attribute Value)
OPTIONSReturn information about endpoint

Note: Methods HEAD, PUT, CONNECT and TRACER are not used in any operation.

Body

The body of the requests and responses must use a JSON content type (i.e., Content-Typeis 'application/json').

Request

  • Requests with mandatory attributes must always send an empty attribute or an empty array (if no items are provided).Arrays with single items must always be sent as a single item array. There is no need to include null/empty fields inrequests with optional attributes.

Responses

  • The name of the fields is always camelCased ASCII strings. The first character is a letter, an underscore (_)or a dollar sign ($).

  • Date attributes use always the UTC ISO format (i.e., %Y-%m-%dT%H:%M:%S.%f+00:00).

  • Arrays without any items are always returned as empty arrays in responses (e.g., {'field': []}).

  • Empty values are always returned as an empty field in the JSON response (e.g., {'field': ''}).

  • Null values, except for strings, are always returned as a null field in the JSON response (e.g., {'field': null}).

  • Null strings are always returned as '' instead of null.

  • Unknown response fields should be ignored by the user.

Response HTTP Codes

API responses always include an appropriated HTTP response code. Below is a non-comprehensive list of used HTTP response codes:

CodeDescription
200 OKWhen request succeeded for a GET or POST request
202 AcceptedWhen a request accepted for a POST that will be completed asynchronously
301 Moved PermanentlyWhen request is placed in a URI without final forward slash
400 Bad RequestWhen request is wrongly format (e.g., doesn't include body)
401 UnauthorizedMissing credentials
403 ForbiddenWrong credentials
404 Not FoundWhen resources are not found
405 Method Not AllowedWhen request uses wrong method (e.g., change_status action using GET)
409 ConflictIndicates that the request could not be processed because of conflict in the request (e.g., object already created)
429 Too Many RequestsWhen a user exceeds the maximum number of requests. Check Throttling section for more information.
415 Unsupported Media TypeWhen request uses wrong content type (e.g., application/xml)
500 Internal Server ErrorWhen there are unexpected server side conditions
503 Service UnavailableTemporary unavailability of the service

The body of the response includes always a 'detail' attribute in the case of errors with information about the error.

Filtering

The URI of the operations returning objects can include parameters to filter the results. The name of the parameter isthe same name of the attribute of the object. For example, to filter the SIM Card list with "label" exactly equal to "car",the URI would be /api/v2.0/sims/?label=Car.

To filter results by date the URI needs to use the date attribute name with the _from and_to suffixes. For example, to filter the Call Detail Records list by "startDate" the URI is:/api/v2.0/sims/123456/cdr/?startDate_from=2014-07-22 00:00:00

For some operations, filtering of nested attributes may be allowed. For example, to filter the SIM Card list by shipping date,the URI would be /api/v2.0/sims/?shippingDate_from=2014-07-22 00:00:00. It is not possible to filterresults based on nested filtering of attributes not returned in the response.

Ordering

The URI of the operations returning objects can include a ordering parameter to order the results. The name of theparameter is the same name of the attribute of the object. For example, to order SIM cards based on "label", the URIis /api/v2.0/sims/?ordering=label.

If the attribute name has dash as a prefix (-), the results will be in descending order.

The results can be ordering based on multiple attributes. For example, to order SIM cards in descending order basedon "label" and ascending order based on MSISDN, the URI is /api/v2./sims/?ordering=-label,msisdn.

Pagination

The endpoints that return a list of object implement pagination. This means that only a maximumnumber of results in returned per request. To control paginated results, you can pass optionalparameters to the endpoint URI.

Below are the valid URI parameters:

ParameterDescriptionAllowed ValuesDefault
pageNumber of the page with resultsPositive integer or last1
per_pageNumber of results per pagePositive integer from 1 to 50050

Example 1: Get two Notifications per page, get the second page.
URI: /api/v2.0/notifications/?per_page=2&page2

The Link header is included in the responses where pagination is relevant (e.g., when returning a list of objects).The header includes links to return specific paginated results on the endpoint. The following are all the possiblerel values:

rel ValueDescription
firstLink to first page of results. This is always included.
lastLink to last page of results. This is always included.
prevLink to previous page of results. Only included when there is a previous page of results.
nextLink to next page of results. Only included when there is a next page of results.

Example 2: Get two Notifications per page, get the last page.
URI: /api/v2.0/notifications/?page=last&per_page=2

Atomicity

Some operations may be atomic (see endpoint description). Atomic operations are performed in all or noneof the objects. Non-atomic operations like Send SMS could result in the SMS being sent only to some SIMs iffor some reason the system was not able to send the SMS to all the SIMs. Your should always confirm the response detailsto make sure the result is what you expected.

Idempotency

To safely retry an API request without accidentally performing the same operation twice, you can attach a unique key to POST requests of idempotent endpoints via the Idempotency-Key: <key> header.

For example, if a request to send an SMS fails due to an error, you can make a second request with the same key to guarantee that only one SMS is sent.

The creation of the key is completely up to you - we suggest using random strings or UUIDs but any value can be used. We'll always send back the same response for requests made with the same key, even if you make the request with different request parameters. The keys are unique per user and endpoint and expire after 24 hours.

Throttling

All requests are throttled to prevent malfunction of the API to users.

The following headers are currently used to guide the API client:

X-RateLimit-LimitNumber of requests available per period
X-RateLimit-ResetMilliseconds left to start a new period
X-RateLimit-RemainingNumber of requests remaining in the current period

Authentication

A Token key must be included in the Authorization HTTP header.The key should be prefixed by the string literal "Token", with whitespace separating the two strings. For example:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

The Token associated with an account can be accessed from the control panel (in the settings section). The Token is always the same for the account (i.e., there is no need to request it every time a new API request is made).

Unauthenticated responses that are denied permission will result in an HTTP 401 Unauthorized responsewith an appropriate WWW-Authenticate header. For example:

WWW-Authenticate: Token

Account Management

Manage account details

Get Organizations

Access the list and the details of the organization.

Filter

You can filter the users list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/organizations/?name=ACME&dateCreated_from=2014-03-05 12:00:00 -> This link will give you the organizations that have the name "ACME" and were created after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/organizations/?ordering=-dateCreated -> This link will give you the organization in descending order of creation. The results are ordered by default based on ascending name of the organizations.

query Parameters
page
integer <int32>
per_page
integer <int32>
name
string

Organization Name

email
string

Email Address

dateCreated_from
string

Earliest Date Created

dateCreated_to
string

Latest Date Created

parentOrganization
string

Organization Name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Sub-Organization details

Access the details of a specific sub-organization given its unique id.

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
{
  • "email": "string",
  • "name": "string",
  • "company_description": "string",
  • "date_created": "2019-08-24T14:15:22Z",
  • "id": "string"
}

Delete Sub-Organization

Delete a sub-organization corresponding to the given ID.

Error 404 - Not Found

This error code will be returned in case the organization with the provided ID either: - Doesn't exist; - You have no permissions to access the organization with provided ID.

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
{ }

Modify Sub-Organization

Partially updates an Organization object. This operation only affects the organization identified in the URL of the request.

This endpoint is idempotent.

To unset a value associated to an attribute, please provide an empty value in the body of the request. For example: {"description": ""}

Error 400 - Bad Request

This error might be returned in case of errors in the request's body. In case this occurs, the description of the error will be sent in the response body, regarding each one of the fields with errors.

Error 404 - Not Found

This error would mean that the organization identified by the provided ID was not found or you don't have permission to access it.

path Parameters
pk
required
string
Request Body schema: application/json
name
string

Organization name

company_description
string

Organization description

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "company_description": "string"
}

Response samples

Content type
application/json
{ }

Get Sub-Organizations

Access the list and the details of the organization.

Filter

You can filter the users list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/sub-organizations/?name=ACME&dateCreated_from=2014-03-05 12:00:00 -> This link will give you the organizations that have the name "ACME" and were created after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/sub-organizations/?ordering=-dateCreated -> This link will give you the organization in descending order of creation. The results are ordered by default based on ascending name of the organizations.

query Parameters
page
integer <int32>
per_page
integer <int32>
name
string

Organization Name

email
string

Email Address

dateCreated_from
string

Created from

dateCreated_to
string

Created until

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Sub-Organization

Create a sub-organization for the user's current organization.

This endpoint is idempotent.

Request Body schema: application/json
email
required
string

Email Address

password
required
string

User's password

role
required
string

User's role in the organization

name
required
string

Organization name

company_description
string

Organization description

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string",
  • "role": "string",
  • "name": "string",
  • "company_description": "string"
}

Response samples

Content type
application/json
{ }

Get Rate Plan Top-Up Limits

Get top-up limits for all rate plans of a sub-organization given its unique id.

path Parameters
pk
required
integer

ID of the sub-organization

query Parameters
rate_plan_id
integer
rate_plan_label
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Rate Plan Top-Up Limit

Create top-up limit for a rate plan of a sub-organization given its unique id.

path Parameters
pk
required
integer

ID of the sub-organization

Request Body schema: application/json
rate_plan_label
required
string

Rate Plan Label

rate_plan_top_up_limit
required
integer

Rate Plan Top Up Limit - Must be greater or equal than 0

Responses

Request samples

Content type
application/json
{
  • "rate_plan_label": "string",
  • "rate_plan_top_up_limit": 0
}

Response samples

Content type
application/json
{
  • "rate_plan_id": 0,
  • "rate_plan_label": "string",
  • "rate_plan_top_up_limit": 0
}

Get Rate Plan Top-Up Limit

Get top-up limit for a rate plan of a sub-organization given its unique id.

path Parameters
pk
required
integer

ID of the sub-organization

id
required
integer

ID of the rate plan

Responses

Response samples

Content type
application/json
{
  • "rate_plan_id": 0,
  • "rate_plan_label": "string",
  • "rate_plan_top_up_limit": 0
}

Update Rate Plan Top-Up Limit

Update top-up limit for a rate plan of a sub-organization given its unique id. Create a new top-up limit if it doesn't exist

path Parameters
pk
required
integer

ID of the sub-organization

id
required
integer

ID of the rate plan

Request Body schema: application/json
rate_plan_top_up_limit
required
integer

Rate Plan Top Up Limit

Responses

Request samples

Content type
application/json
{
  • "rate_plan_top_up_limit": 0
}

Response samples

Content type
application/json
{
  • "rate_plan_id": 0,
  • "rate_plan_label": "string",
  • "rate_plan_top_up_limit": 0
}

Delete Rate Plan Top-Up Limit

Delete top-up limit for a rate plan of a sub-organization given its unique id.

path Parameters
pk
required
integer

ID of the sub-organization

id
required
integer

ID of the rate plan

Responses

Response samples

Content type
application/json
{
  • "detail": "Rate plan top-up limit deleted successfully"
}

Get Rate Plan Top-Up counter

Get top-up counter for a rate plan of a sub-organization given its unique id.

path Parameters
pk
required
integer

ID of the sub-organization

id
required
integer

ID of the rate plan

Responses

Response samples

Content type
application/json
{
  • "rate_plan_top_up_usage": 0
}

User Management

Manage user details

Get User details

Access the the details of a specific users of an organization.

Error 404 - Not Found

This error will be returned in case there is no user with the selected key.

path Parameters
id
required
string
query Parameters
id
string

User ID

organization
string

Organization Name

firstName
string

First Name

lastName
string

Last Name

email
string

Email Address

dateJoined_from
string

Earliest Date Joined

dateJoined_to
string

Latest Date Joined

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "role": "string",
  • "dateJoined": "2019-08-24T14:15:22Z",
  • "organization": "string"
}

Delete User

Delete a user corresponding to the given ID.

Error 403 - Forbidden

This error is returned in case you don't have permission to, either:

- Access the user's organization.
- Delete users of the user's current role.
path Parameters
id
required
string
query Parameters
id
string

User ID

organization
string

Organization Name

firstName
string

First Name

lastName
string

Last Name

email
string

Email Address

dateJoined_from
string

Earliest Date Joined

dateJoined_to
string

Latest Date Joined

Responses

Response samples

Content type
application/json
{ }

Modify User

Updates a specific user of an organization. This operation only affects the user identified in the URL of the request.

This endpoint is idempotent.

To unset a value associated to an attribute, please provide an empty value in the body of the request. For example: {"firstName": ""}

Error 400 - Bad Request

This error might be returned in case of errors in the request's body. In case this occurs, the description of the error will be sent in the response body, regarding each one of the fields with errors.

Error 403 - Forbidden

This error is returned in case you don't have permission to, either:

- Create users of the Role you want to update the user to.
- Move the user to an organization you don't have access to.
- Update users of the user's current role.
- Access user's current organization.
path Parameters
id
required
string
Request Body schema: application/json
firstName
string

First Name

lastName
string

Last Name

email
string

Email Address

role
string

User's role in the organization

organization
string

Organization Name

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "role": "string",
  • "organization": "string"
}

Response samples

Content type
application/json
{ }

Get Users

Access the list and the details of users of your organization.

Filter

You can filter the users list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/users/?firstName=John&dateJoined_from=2014-03-05 12:00:00 -> This link will give you the users that have the first name "John" and joined after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/users/?ordering=-dateJoined -> This link will give you the users in descending order of joining. The results are ordered by default based on ascending date that users joined.

query Parameters
page
integer <int32>
per_page
integer <int32>
id
string

User ID

organization
string

Organization Name

firstName
string

First Name

lastName
string

Last Name

email
string

Email Address

dateJoined_from
string

Earliest Date Joined

dateJoined_to
string

Latest Date Joined

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create User

Create a user for your organization or for one of your sub organization.

This endpoint is idempotent.

Error 400 - Bad Request

This error might be returned in case of errors in the request's body. In case this occurs, the description of the error will be sent in the response body, regarding each one of the fields with errors.

Error 403 - Forbidden

This error is returned in case you don't have permission to, either:

- Create users with the Role you provided.
- Create users for an organization you don't have access to.
Request Body schema: application/json
firstName
string

First Name

lastName
string

Last Name

email
required
string

Email Address

password
required
string

User's password

organization
required
string

Organization Name

role
required
string

User's role in the organization

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "email": "string",
  • "password": "string",
  • "organization": "string",
  • "role": "string"
}

Response samples

Content type
application/json
{ }

SIM Cards

Change Data Status

Change the Data Status for one or more SIM cards

This endpoint is idempotent.

Request Body schema: application/json
iccid
required
Array of strings

List of strings of ICCIDs

status
required
string

New Data Status (options: ACTIVE, SUSPENDED)

Responses

Request samples

Content type
application/json
Example
{
  • "iccid": [
    ],
  • "status": "SUSPENDED"
}

Response samples

Content type
application/json
{
  • "detail": "OK"
}

Get Ongoing Sessions

Access the list and the details of the ongoing data sessions.

Filter

You can filter the Ongoing Sessions list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes)

query Parameters
page
integer <int32>
per_page
integer <int32>
iccid
string

ICCID

fromStartDate
string

Start Date From

toStartDate
string

Start Date To

ipAddress
string

IP Adress

fromDuration
string

Duration from

toDuration
string

Duration to

mcc
string

MCC

mnc
string

MNC

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get SIM Card Subscription

Access to the subscription information for a specific SIM Card.

path Parameters
iccid
required
string

Responses

Response samples

Content type
application/json
{
  • "subscription": {
    }
}

Modify SIM Card Subscription

Modify elements for the SIM Card the subscription. Only some fields are eligible to be patch such as:

servicePackId (i.e. SIM Card Rate Plan):

- The new Service Pack will only be applicable at the next Billing Cycle
- If there is a new Service Pack to be applied at the next Billing Cycle, you can revert the action by sending a PATCH request
with the servicePackId that is currently used.

Note: The remaining fields are directed correlated to the changeable fields or cannot be patched.

Error 400 - Bad Request

This error appears when the body requests is malformed. Possible errors:

servicePackId

  • Unknown Rate Plan with label {servicePackId}. - The Rate Plan with the Label = {servicePackId} does not exists.

Error 404 - Not Found

This error appears if the SIM Cards with {iccid} is not in your Organization.

path Parameters
iccid
required
string
Request Body schema: application/json
servicePackId
string

SIM Card Service Pack Id (i.e. Rate Plan)

Responses

Request samples

Content type
application/json
{
  • "servicePackId": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Change SIM status

Change the status of one or more SIM cards

This endpoint is idempotent.

Request Body schema: application/json
iccid
required
Array of strings

List of strings of ICCIDs

status
required
string

New SIM Card Status (options: TEST, PROVISIONED, PRE-ACTIVE, ACTIVE, SUSPENDED, RETIRED)

Responses

Request samples

Content type
application/json
Example
{
  • "iccid": [
    ],
  • "status": "PRE_ACTIVE"
}

Response samples

Content type
application/json
{
  • "detail": "OK"
}

Get SMS status

Access the delivery report of an SMS sent using the API.

Filter

You can filter the Notifications list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/send_sms/status/?date_from=2014-03-05 12:00:00 -> This link will give you the reports of SMSs that were submitted after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/send_sms/status/?ordering=dateSubmitted -> This link will give you the results in ascending order of submission date. The results are ordered by default based on ID in descending order.

query Parameters
page
integer <int32>
per_page
integer <int32>
id
string

ID

dateSubmitted
string

Submitted Date

content
string

Content

dateSubmitted_from
string

Earliest Submitted Date

dateSubmitted_to
string

Latest Submitted Date

iccid
string

ICCID

deliveryStatus
string

Delivery Status

o
string
Value: "-id"

Ordering

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Send SMS

Send an SMS to one or more SIM cards

This endpoint is idempotent.

Request Body schema: application/json
iccid
required
Array of strings

List of strings of ICCIDs

text
required
string

Text for the SMS

Responses

Request samples

Content type
application/json
{
  • "iccid": [
    ],
  • "text": "This is a text message"
}

Response samples

Content type
application/json
{}

Get SMS details

Access the delivery report of an SMS sent using the API.

Filter

You can filter the Notifications list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/send_sms/status/?date_from=2014-03-05 12:00:00 -> This link will give you the reports of SMSs that were submitted after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/send_sms/status/?ordering=dateSubmitted -> This link will give you the results in ascending order of submission date. The results are ordered by default based on ID in descending order.

path Parameters
id
required
string
query Parameters
id
string

ID

dateSubmitted
string

Submitted Date

content
string

Content

dateSubmitted_from
string

Earliest Submitted Date

dateSubmitted_to
string

Latest Submitted Date

iccid
string

ICCID

deliveryStatus
string

Delivery Status

o
string
Value: "-id"

Ordering

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "dateSubmitted": "2019-08-24T14:15:22Z",
  • "content": "string",
  • "deliveryReport": [
    ]
}

Get SIM Card details

Access the details of a specific SIM card.

path Parameters
iccid
required
string

Responses

Response samples

Content type
application/json
{
  • "iccid": "string",
  • "label": "string",
  • "description": "string",
  • "simType": "string",
  • "primaryMsisdn": "string",
  • "msisdns": [
    ],
  • "primaryImsi": "string",
  • "imsis": [
    ],
  • "gsmKeys": {
    },
  • "dates": {
    },
  • "imei": "string",
  • "subscription": {
    },
  • "attributes": [
    ],
  • "tags": [
    ],
  • "location_tag": {
    },
  • "organization": "string"
}

Modify SIM Card

Update some fields from the selected SIM Cards.

You can also change the SIM Card Organization and

path Parameters
iccid
required
string
Request Body schema: application/json
label
string

SIM Card Label

description
string

SIM Cards Description

organization
string

Organization Name

Responses

Request samples

Content type
application/json
Example
{
  • "organization": "Truphone Test 1000"
}

Response samples

Content type
application/json
{ }

Change SMS Status

Change the SMS (Mobile Originated or Terminated) Services for one or more SIM cards.

This endpoint is idempotent.

Request Body schema: application/json
iccid
required
Array of strings

List of strings of ICCIDs

sms_service
required
string
Enum: "MO" "MT"

Select which SMS Service to apply the change.

status
required
string
Enum: "ACTIVE" "SUSPENDED"

Select the change to perform to the SMS Service

Responses

Request samples

Content type
application/json
Example
{
  • "iccid": [
    ],
  • "sms_service": "MO",
  • "status": "SUSPENDED"
}

Response samples

Content type
application/json
{
  • "detail": "OK"
}

Get SIM Card Status

Check the SIM card service status.

path Parameters
iccid
required
string

Responses

Response samples

Content type
application/json
{
  • "iccid": "string",
  • "status": "string",
  • "date": "string",
  • "test_state_start_date": "2019-08-24T14:15:22Z",
  • "allowed_data": "string",
  • "allowed_time": "string",
  • "remaining_data": "string",
  • "remaining_time": "string"
}

Get SIM Cards

Access the list and the details of the SIM cards in your account.

Filter

You can filter the SIM Card list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes)

/api/sims/?label=Car&firstActivationDate_from=2014-03-05 12:00:00
This link will give you the SIM Cards that have a label with "Car" and were activated after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model.

/api/sims/?ordering=-iccid
This link will give you the SIM Cards in descending order of ICCID. The results are ordered by default based on ascending
ICCID of the SIM cards.

Changelog

From v2.1 to v2.2

- Added organization field to the Response Model
query Parameters
page
integer <int32>
per_page
integer <int32>
iccid
string

ICCID

label
string

Label

description
string

Description

primaryMsisdn
string

Primary MSISDN

msisdns
string

MSISDN

primaryImsi
string

Primary IMSI

imsis
string

IMSI

servicePackId
string
tags
string
attributes
string
pin1
string

PIN1

pin2
string

PIN2

puk1
string

PUK1

puk2
string

PUK2

provisionDate_from
string

Earliest Provision Date

provisionDate_to
string

Latest Provision Date

shippingDate_from
string

Earliest Shipping Date

shippingDate_to
string

Latest Delivery Date

deliveryDate_from
string

Earliest Delivery Date

deliveryDate_to
string

Latest Delivery Date

firstActivationDate_from
string

Earliest Date of First Activation

firstActivationDate_to
string

Latest Date of First Activation

subscriptionStatus
string

Status

apn
string

Access Point Name

simType
string
locationTag_label
string
testStateStartDate_from
string

Earliest Test State Start Date

testStateStartDate_to
string

Latest Test State Start Date

organization
string

Organization Name

Responses

Response samples

Content type
application/json
[
  • {
    }
]

SIM Tags and Attributes

Get SIMs with Tag

Access the Tag details with the selected label.

path Parameters
label
required
string
query Parameters
page
integer <int32>
per_page
integer <int32>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Assign Tag to SIM Card

Associate a Tag to a SIM Card.

path Parameters
label
required
string
Request Body schema: application/json
simCards
Array of strings

String list of SIM Card ICCID(s)

Responses

Request samples

Content type
application/json
{
  • "simCards": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Unassign Tag from SIM Card

Remove a Tag from a SIM Card.

path Parameters
label
required
string
Request Body schema: application/json
simCards
Array of strings

String list of SIM Card ICCID(s)

Responses

Request samples

Content type
application/json
{
  • "simCards": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get Tag details

Access the Tag details with the selected label.

path Parameters
label
required
string

Responses

Response samples

Content type
application/json
{
  • "simCards": [
    ],
  • "label": "string",
  • "description": "string"
}

Delete Tag

Delete a Tag associated to your Organization.

path Parameters
label
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Delete Attribute

Delete an Attribute associated to your Organization.

Error 404 - Not Found

This error appears if an Attribute with {label} is not created in your Organization. Use the method POST /api/v2.0/attributes/ to create a new Attribute

path Parameters
label
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "string"
}

Set Attribute Value

Set the value of the Attribute in one or more SIM Cards in the list. This operation only affects the SIM(s) included in the body of the request. The value of the attribute of the other SIMs will remain unchanged.

To unset a value associated to an attribute, please send an empty value in the body of the request. For example: {"label="label name", "simCards": ['iccid_1'], "value" : ""}

Error 400 - Bad Request

This error appears when the requests is malformed. Possible errors:

SIM Cards

  • This field is required. - simCards is required in the PATCH body.
  • This list may not be empty - Need to add a list of SIM Card to your request.
  • SIM card(s) with ICCID(s) ['iccid_1', ... ] unknown - One or more SIM Cards do not exists in your Organization.

Error 404 - Not Found

This error appears if an Attribute with {label} is not created in your Organization. Use the method POST /api/v2.0/attributes/ to create a new Attribute

path Parameters
label
required
string
Request Body schema: application/json
simCards
Array of strings

String list of SIM Card ICCID(s)

value
string

Value to associate the Attribute

Responses

Request samples

Content type
application/json
{
  • "simCards": [
    ],
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get Tags

Access the list and the details of the account tags.

Filter

You can filter the Tags list using the name of the attributes associated with the model, e.g. /api/tags/?label=test -> This link will give you the Tags that have label test

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/tags?ordering=-label -> This link will give you the results in desscending order of label. The results are ordered by default based on ascending label.

query Parameters
page
integer <int32>
per_page
integer <int32>
simCard
string

SIM Card ICCID

label
string

Label

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Tag

Add a new tag to the Organization.

Request Body schema: application/json
label
required
string

Valid Tag label - must contain only alphanumeric and whitespaces

description
required
string

Small text to describe the Tag

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Get Attributes

Access the list and details for the organization Attributes. Each entry will have the associated SIM card and a value if it was added.

Filter

You can filter the Attributes list using the name of the attributes associated with the model. e.g. /api/attributes/?label=test -> This link will give you the Attributes with the label 'test'

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/attributes?ordering=-label -> This link will give you the results in descending order for field 'label'. Note: The results are ordered by default based on ascending label.

query Parameters
page
integer <int32>
per_page
integer <int32>
simCard
string

SIM Card ICCID

label
string

Label

value
string

Value

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Attribute

Add a new Attribute to the Organization SIM Cards. The SIM Card value associated with the Attribute will be empty. Use the method PATCH /api/v2.0/attributes/{label}/ to associate a value.

Error 400 - Bad Request

This error appears when the body requests is malformed. Possible errors:

Label

  • This field is required. - Label is required in the POST body.
  • This field may not be blank. - This field must not be blank.
  • Only alphanumeric or whitespace characters are allowed. - Remove any special characters from the Label.

Description

  • This field is required. - Description is required in the POST body but can be blank. (e.g. { "description":""} ).

Error 409 - Conflict

This error appears if an Attribute is already created in your Organization. The response body detail will contain further details.

Request Body schema: application/json
label
required
string

Valid Attribute label - must contain only alphanumeric and whitespaces

description
required
string

Small text to describe the Attribute

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Usage and Event Rules

Rules enable automatic connectivity management

Get Rules

Access the list and the details of the rules active in the account.

Ordering

The results are ordered by default based on ascending date of creation.

Note: This endpoint does not support filtering nor configured ordering.

query Parameters
page
integer <int32>

The page to retrieve

per_page
integer <int32>

The maximum number of items to retrieve

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Rule Events

Access the list and the details of the events related with the rules.

Filter

You can filter the Rules Events list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/rules/events/?date_from=2014-03-05 12:00:00 -> This link will give you the rules events that happened after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/rules/events?ordering=date -> This link will give you the results in ascending order of date. The results are ordered by default based on descending date (i.e., most recent first).

query Parameters
page
integer <int32>
per_page
integer <int32>
date
string

Date

label
string

Label

simCard
string

SIM Card ICCID

type
string

Type

message
string

Message (filters based on substring)

email
string

Email

mobilePhoneNumber
string

Mobile Number

url
string

URL

date_from
string

Earliest Date

date_to
string

Latest Date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Event Rule details

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Delete Event Rule

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "Not Found"
}

Modify Event Rule

path Parameters
pk
required
string
Request Body schema: application/json
label
string

Title of the rule

description
string

Additional description of the rule

object (RulesFilterSerializer)
object (RulesActionSerializer)
object (RulesNotificationSerializer)
object (EventRuleConditionSerializer)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Get Usage Rules

query Parameters
page
integer <int32>
per_page
integer <int32>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Usage Rule

Request Body schema: application/json
label
string

Title of the rule

description
string

Additional description of the rule

object (RulesFilterSerializer)
object (RulesActionSerializer)
object (RulesNotificationSerializer)
object (UsageRuleConditionSerializer)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Get Event Rules

query Parameters
page
integer <int32>
per_page
integer <int32>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Event Rule

Request Body schema: application/json
label
string

Title of the rule

description
string

Additional description of the rule

object (RulesFilterSerializer)
object (RulesActionSerializer)
object (RulesNotificationSerializer)
object (EventRuleConditionSerializer)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Get Usage Rule details

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Delete Usage Rule

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
{
  • "detail": "Not Found"
}

Modify Usage Rule

path Parameters
pk
required
string
Request Body schema: application/json
label
string

Title of the rule

description
string

Additional description of the rule

object (RulesFilterSerializer)
object (RulesActionSerializer)
object (RulesNotificationSerializer)
object (UsageRuleConditionSerializer)

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "label": "string",
  • "description": "string",
  • "filters": {
    },
  • "action": {
    },
  • "notifications": {
    },
  • "condition": {
    }
}

SIM Usage

Get Call Detail Record Details

Access the details of a specific Call Detail Record.

path Parameters
iccid
required
string
cdr_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "856346526",
  • "simCard": "8944479999999999999",
  • "startDate": "2022-01-07T09:39:15+00:00",
  • "endDate": "2022-01-07T09:39:20+00:00",
  • "duration": 50,
  • "origin": null,
  • "destination": null,
  • "country": "United Kingdom",
  • "network": "Truphone UK",
  • "type": "DATA"
}

Get Call Detail Records

Access the list and the details of the Call Detail Records associated with SIM cards in your account.

Filter

You can filter the Call Detail Records list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/sims/12345/cdr/?country=spain&startDate_from=2014-03-05 12:00:00 -> This link will give you the Call Detail Records that have the country "spain" were started after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/sims/12345/cdr/?ordering=-country -> This link will give you the results in descending order of country. The results are ordered by default based on descending start date (i.e., most recent first).

path Parameters
iccid
required
string
query Parameters
page
integer <int32>
per_page
integer <int32>
id
string

ID

duration
string

Duration

origin
string

Origin

destination
string

Destination

location
string

Location

country
string

Country

network
string

Network

type
string
Enum: "SMS_IN" "SMS_OUT" "DATA"
startDate_from
string

Earliest Start Date

startDate_to
string

Latest Start Date

endDate_from
string

Earliest End Date

endDate_to
string

Latest End Date

duration__gte
string

Duration Greater of Equal Than

duration__lte
string

Duration Lower or Equal Than

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Location Updates

Get location updates

Access the list and the details of the Location Updates associated with SIM cards in your account

Filter

You can filter the Location Updates list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/sims/12345/location/?country=spain&date_from=2014-03-05 12:00:00 -> This link will give you the Location Update that have the country "Spain" was received after 2014-03-05 12:00:00 The results are ordered by default based on descending date (i.e., most recent first).

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/sims/12345/location/?ordering=-country -> This link will give you the results in descending order of country.

path Parameters
iccid
required
string
query Parameters
page
integer <int32>
per_page
integer <int32>
id
string

ID

date
string

Date

country
string

Country

network_name
string

Network Name

date_from
string

Earliest Date

date_to
string

Latest Date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get location update details

Access the details of a specific Location Update.

path Parameters
iccid
required
string
id
required
string
query Parameters
id
string

ID

date
string

Date

country
string

Country

network_name
string

Network Name

date_from
string

Earliest Date

date_to
string

Latest Date

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "simCard": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "country": "string",
  • "networkName": "string"
}

Devices

Get Device details

Access the the details of a specific device, based on the provided IMEI number.

Error 404 - Not Found

This error will be returned in case there is no devices with the selected key.

path Parameters
imei
required
string

Responses

Response samples

Content type
application/json
{
  • "imei": "string",
  • "organization": "string",
  • "dateFirstRegistered": "2019-08-24T14:15:22Z",
  • "dateLatestUpdate": "2019-08-24T14:15:22Z",
  • "label": "string",
  • "description": "string",
  • "iccid": "string"
}

Modify Device

Updates a specific device. This operation only affects the device identified in the URL of the request, by its IMEI number.

This endpoint is idempotent.

To unset a value associated to an attribute, please provide an empty value for that field in the body of the request. For example: {"label": ""}

Error 400 - Bad Request

This error might be returned in case of errors in the request's body. In case this occurs, the description of the error will be sent in the response body, regarding each one of the fields with errors.

path Parameters
imei
required
string
Request Body schema: application/json
label
string

Label

description
string

Description

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{ }

Get Devices

Access the list and the details of devices of your organization (including sub-organizations).

Filter

You can filter the devices list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/devices?organization=ExampleOrg&iccid=1234 -> This link will give you the devices that belong to organization named "ExampleOrg" and are associated to SIM cards identified by ICCID containing "1234".

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/devices?ordering=-imei -> This link will give you the devices in descending IMEI order.

query Parameters
page
integer <int32>
per_page
integer <int32>
imei
string

International Mobile Station Equipment Identity

organization
string
dateFirstRegistered
string

Date when the device was first registered

dateLatestUpdate
string

Latest update date

label
string
description
string
iccid
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reports

Generate Reports

Generate reports with the same conditions as the report session wizard in the Portal. This endpoint will generate a CSV or JSON response, depending on the options you choose, the download link is available for one hour.

Request Body schema: application/json
report_type
required
string
Enum: "INVENTORY" "LOCATION" "DATA_USAGE" "SMS_USAGE" "EVENT_RULES" "USAGE_RULES" "NOTIFICATIONS"

Choose the report type

iccid
Array of objects

List of ICCIDs - each separated by a comma (e.g. iccid1,iccid2).

tag
Array of objects

List of Tags - each separated by a comma (e.g. tag1,tag2).

all_sim_cards
boolean

Uses All SIM Cards from the organization.

granularity
required
string
Enum: "Month" "Cycle" "Day" "Hour"

Select the report granularity - Hourly (Max: 7 Days) Daily (Max: 6 Months).

billing_cycle
integer <int64>

Select the starting day of the billing cycle (e.g. 5, 20).

period
string
Enum: "PAST_7_DAYS" "PAST_14_DAYS" "PAST_30_DAYS" "PAST_3_MONTHS" "PAST_6_MONTHS" "PAST_1_YEAR"

The period selected ends in the current day.

startDate
string <date-time>

Date format: YYYY-MM-DD HH:MM:SS

endDate
string <date-time>

Date format: YYYY-MM-DD HH:MM:SS

output_format
required
string
Enum: "CSV" "JSON"

Select the output format you prefer.

Responses

Request samples

Content type
application/json
{
  • "report_type": "DATA_USAGE",
  • "all_sim_cards": true,
  • "granularity": "Day",
  • "period": "PAST_7_DAYS",
  • "output_format": "CSV"
}

Response samples

Content type
application/json
{}

Download Report

Download the generated reports previously, the download link has a expired time of 1 Hour and the response comes as JSON or CSV depending on the options selected.

path Parameters
pk
required
string

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Billing

Get Rateplan Details

Access to the subscription information for a specific Rate Plan. This version contains the Test Mode information.

path Parameters
servicePackId
required
string

Responses

Response samples

Content type
application/json
{
  • "servicePackId": "string",
  • "bearerServices": {
    },
  • "supportsTestMode": true,
  • "testMode": {
    }
}

Get Rateplans

Access the Rate Plans list and related details associated to your account. This version contains the Test Mode information.

Filter

You can filter the Rate Plans list using the following fields:

- servicePackId
- supportsTestMode

Examples:

- /api/rate_plan/?servicePackId=Pre%20Paid -> This link will give you the Rate Plans with "Pre Paid" in the servicePackId
- /api/rate_plan/?supportsTestMode=True -> This link will give you the Rate Plans that support the Test State

Ordering

You can only order the results using the servicePackId field.

- /api/users/?ordering=-servicePackId -> This link will give you the RAte Plans in descending order by servicePackId.
query Parameters
page
integer <int32>
per_page
integer <int32>
servicePackId
string

Service Pack ID

supportsTestMode
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Notifications

Get Notifications

Access the list and the details of the account notifications.

Filter

You can filter the Notifications list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/notifications/?date_from=2014-03-05 12:00:00 -> This link will give you the Notifications that happened after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/notifications?ordering=date -> This link will give you the results in ascending order of date. The results are ordered by default based on descending date (i.e., most recent first).

query Parameters
page
integer <int32>
per_page
integer <int32>
type
string

Type

sourceType
string

Source Type

source
string

Source

date
string

Date

value
string

Value

attributeType
string

Attribute Type

state
string

State

date_from
string

Earliest Date

date_to
string

Latest Date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Audit Trail

Get Audit Trail

Access the list and the details of the account audit trail entries.

Filter

You can filter the AuditTrail list using the name of the attributes associated with the model, except for the attributes related to dates (see Attributes) e.g. /api/audit_trail/?date_from=2014-03-05 12:00:00 -> This link will give you the Audit Trail entries that happened after 2014-03-05 12:00:00

Ordering

You can order the results using the name of the attributes associated with the model. e.g. /api/audit_trail?ordering=user -> This link will give you the results in ascending order of user. The results are ordered by default based on descending date (i.e., most recent first).

query Parameters
page
integer <int32>
per_page
integer <int32>
date
string

Date

user
string

User

interface
string

Interface

object_type
string

Object Type

object
string

Object

action
string

Action

description
string

Description

date_from
string

Earliest Date

date_to
string

Latest Date

Responses

Response samples

Content type
application/json
[
  • {
    }
]