Back to top

EMnify Rest API

Accessing the API

The system provides a RESTful API. Communication with the API is done over HTTP(S) requests with JSON body content and content-type “application/json” with an authentication token as a requirement for every API call. All API calls must be made over https.

The API is defined in detail in the following section, but here are some highlights:

  • Lookup values are accessed at the same level as the resource they describe. For example, the URL to retrieve the list of possible statuses of an endpoint is /api/v1/endpoint/status.

  • Collection responses are NOT wrapped in an envelope. Instead the result metadata is returned in the header of the response.

  • Paging, filtering sorting of large datasets are managed via query parameters of GET command.

  • API provides complex error messages capable of reporting a set of errors.

  • API implicitly provides multi-tenancy management. The server limits the visibility of the data and available operations based on the organisation of the user identified by authentication token.

  • When associating an existing object(s) to a collection, it is sufficient to provide only the object(s) IDs.

The following service pattern is provided for all major resources:

Action URL Description
GET /api/v1/resource retrieve resource collection
POST /api/v1/resource create resource
GET /api/v1/resource/{id} retrieve single resource
PATCH /api/v1/resource/{id} update single resource
DELETE /api/v1/resource/{id} delete single resource
PUT /api/v1/resource/{id1}/collection/{id2} add item with id id2 to a collection of a resource with id id1.

N.B. Word endpoint, typically used in RESTful API definition has a particular meaning in EMnify application domain. To avoid confusion, in this specification the word endpoint will be used to identify endpoint entity (resource) of EMnify system domain, while the word entrypoint will be used to identify generic RESTful API endpoint.

Securing the API

The API is secured through usage of JSON Web Tokens (JWT) which are an open standard [RFC 7519] (https://tools.ietf.org/html/rfc7519) for representing claims securely between two parties.

The server generates JWT tokens for accessing the API (further referenced as ‘authentication token’) for users or applications after they present verifiable credentials. Once the credentials are exchanged for an authentication token on the server, the client has to submit it within the HTTP Authorisation header in each subsequent request. The system validates the rights and permissions of the requesting user/application by parsing the token’s content.

The authentication token expires after 240 minutes. Therefore the authentication needs to be performed again to obtain a new authentication token.

If the authentication token is missing, invalid or expired the API returns 401 Unauthorized response status.

If a client tries to access resources that exists, but the client does not have the permissions or the rights to access it, the API returns either 403 Forbidden or 404 Not Found.

These requirements are general and will not be repeated in in the remainder of this API specification.

Connection

All API calls including the authentication must be made over secure socket (SSL).

Server is responding to API request in gzip compressed format with header

Content-Encoding: gzip
Content-Type: application/json

URL format

All API URLs are following a generic structure like

/api/APIVERSION/ENTRYPOINT/{object_id}

e.g.

/api/v1/user/123

Also some resources may provide access to further sub-resources

/api/v1/organisation/123/contact

HTTP verbs

Here is the definition of HTTP verbs used in the API with description and typical responses upon request to collection entrypoint and single resource entrypoint.

VERB Description Collection Response
i.e. /sim		 Item Response
i.e. /sim/{id}
GET retrieves a representation of a resource without side-effects (nothing changes on the server) 200 (OK), list of SIMs. Use pagination, sorting and filtering to navigate big lists. 200 (OK), single SIM. 404 (Not Found), if ID not found or invalid.
HEAD retrieves just the resource meta-information (headers) e.g. same as GET but without the response body - also without side-effects TBD
OPTIONS returns the actions supported for specified the resource - also without side-effects TBD
POST creates a resource 201 (Created), ‘Location’ header with link to /sim/{id} containing new ID. 404 (Not Found).
PUT (completely) replaces an existing resource 404 (Not Found) 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
PATCH partial modification of a resource 404 (Not Found) 200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE deletes a resource 404 (Not Found) 200 (OK). 404 (Not Found), if ID not found or invalid.

HTTP Headers

Request Headers

Each HTTP request must have at least the following headers:

  • Content-Type: application/json

  • Accept: application/json

  • Authorization: Bearer YourAuthenticationToken

Response Headers

The API uses header to transfer meta information about the returned result. The usage varies depending on the operation. The details are available within the specification of particular resource description:

Header Description Example
Location [POST] - URL of the created resource Location: /api/v1/endpoint/123
Link [GET] Collection - URL of available pages Link:
https://cdn.emnify.net/api/v1/endpoint?per_page=100; rel=“first”,
https://cdn.emnify.net/api/v1/endpoint?page=5&per_page=100; rel=“prev”,
https://cdn.emnify.net/api/v1/endpoint?page=7&per_page=100; rel=“next”,
https://cdn.emnify.net/api/v1/endpoint?page=34&per_page=100; rel=“last”
X-Total-Count [GET] Collection - Total item count X-Total-Count: 3325
X-Current-Page [GET] Collection - Current page X-Current-Page: 6
X-Filter [GET] Collection - Filter applied criteria X-Filter: status:1
X-Sort [GET] Collection - Applied sort criteria X-Sort: -status

HTTP Return codes

CODE Meaning Description
200 OK Response to a successful GET, also used for a POST if it does not result in a creation
201 Created Response to a POST that results in a creation, usually will return a Location header pointing to the location of the new resource
204 No Content Response to a successful request that is not returning a body
400 Bad Request The request is malformed, e.g. the body cannot be parsed
401 Unauthorized No or invalid authentication token provided
403 Forbidden authentication token is valid, but user has no access permissions to the request resource
404 Not Found A non-existent resource is requested
405 Method Not Allowed HTTP method being requested is not allowed
409 Conflict The request could not be completed due to a conflict with the current state of the resource.
410 Gone Indicates that the resource at this end point is no longer available.
415 Unsupported Media Type Incorrect content type was provided as part of the request
422 Unprocessable Entity Body will return list of validation errors
429 Too Many Requests Request is rejected due to rate limiting

Error Handling

The API will return HTTP error codes according to the type of the error, 400 error codes are used for client related issues, 500 error codes for server side issue.

JSON error representation

403 status code is returned with the following JSON error:

{
  "error_code" :  1104,
  "error_token": "Forbidden",
   "message": "You do not have the necessary permissions to access this entry point. Please contact your administrator."
}

400 error codes come with a consumable JSON error representation:

{
  "error_code" : 1406,
  "error_token" : "NotAllowed",
  "message" : "Updating of own organisation not allowed.",
}

Some error codes like ValidationFailed can contain multiple error messages embedded

{
  "error_code" : 1400,
  "error_token" : "InputValidationFailed",
  "message" : "Input validation failed",
  "errors" : [
    {
      "error_code" : 1403,
      "error_token" : "InvalidFormat",
      "message" : "User - Username has invalid format: expecting String."
    },
    {
      "error_code" : 1402,
      "error_token" : "Required",
      "message" : "User - organisation is required."
    }
  ]
}

List of Error Codes

Generic Error Codes

There are several error categories that have general applicability within API and are not specific to any particular resource.

Category HTTP
Status		 Error
Code		 Error
Token		 Description
and parameters
Authentication 401 1101 InvalidCredentials
Authentication 401 1102 InvalidToken
Authentication 401 1103 TokenExpired
Authentication 403 1104 Forbidden
Authentication 429 1105 TooManyRequests
Navigation 404 1201 NotFound {resource} with id {id} not found
Paging 422 1301 InvalidQueryCriteria Search criteria {criteria} is invalid
Paging 422 1302 InvalidSortCriteria Sort criteria {criteria} is invalid
Validation 422 1400 InputValidationFailed
Validation 422 1401 InvalidReference Invalid reference to {resource} with id {id}
Validation 422 1402 Required {Object} - {field} is required
Validation 422 1403 InvalidFormat {Object} - {field} has invalid format: Expecting {String/Number/Object}
Validation 422 1404 OutOfRange {Object} - {field} out of range ({range})
Validation 409 1405 Duplicated {Object} - {field} already exists
Validation 400 1406 NotAllowed {Action} not allowed
Validation 409 1407 CannotBeDeleted {Object} still referenced
Validation 422 1408 InvalidValue {Object} - {field} is invalid: {value}
Validation 422 1409 UnknownProperty Unknown Property: {property}
Rate Limit 429 1501 TooManyRequests Too many requests
Unavailable 404 1601 Unavailable No {resource} available
Connectivity 404 1901 UnknownSubscriber Unknown Subscriber for Endpoint with id {id}
Connectivity 404 1904 UnknownLocation Unknown Location for Endpoint with id {id}

General errors are defined in this section and are not repeated throughout the specification.

Resource Specific Errors

Errors that are specific to a particular resource and operation being performed are described in resource section.

Most of the errors in this category return 409 Conflict HTTP status code.

For example, trying to activate an endpoint that has no SIM card associated will cause the following error:

409 Conflict
{
  "error_code" : 2101,
  "error_token" : "UnableToActivate",
  "message" : "Unable to activate",
  "description" : "No SIM."
}

Error specific errors are segmented as follows:

Code Range Resource
2100-2199 Endpoint
2200-2299 SIM
2300-2399 Service profiles
2400-2499 Traffic limits
2500-2599 User
2600-2699 Tariff

Working With Collections - paging, filtering, sorting and sub-entity expansion

API supports paging, filtering, sorting on big lists ([GET] operation on collection resources). Paging, filtering and sorting are handled as query parameters in requests, while meta data describing the response are returned as header parameters.

N.B. Only the collection GET requests that handle large datasets implement this functionality.

Paging

Paging accepts query parameters that specify:

  • per_page - maximum number of resources to be retrieved within a single response (page size)

    • If per_page is < 1 the default page size is used
    • per_page is set to a predefined maximum value if it`s too big

  • page - number of returned chunk within the complete set (page#).

    • If the requested page does not exist the first (for page < 1) or the last page (for page > last_page) is returned

The response header contains:

  • Link - URLs for navigational links used to retrieve first, previous, next and last page in a dataset

  • X-Count-Per-Page - Requested per_page parameter

  • X-Current-Page - Current page number within the set

  • X-Total-Count - Total element count in the dataset

  • X-Total-Pages - Total pages count in the dataset

Example

Request

curl -v -H "Authorization: Bearer YourAuthenticationToken" "https://cdn.emnify.net/api/v1/endpoint?page=3&per_page=100"

Response header

Link:  <https://cdn.emnify.net/api/v1/endpoints?per_page=100>; rel="first", <https://cdn.emnify.net/api/v1/endpoints?page=2&per_page=100>; rel="prev", <https://cdn.emnify.net/api/v1/endpoints?page=4&per_page=100>; rel="next", <https://cdn.emnify.net/api/v1/endpoints?page=50&per_page=100>; rel="last"
X-Count-Per-Page: 100
X-Current-Page: 3
X-Total-Count: 5000
X-Total-Pages: 50

N.B. Link header should contain any (optional) filter, sort and expansion query parameters.

Filtering

Filtering criteria will be included in the request URL as {q} parameter as a comma separated list of field:criteria pairs

# filter arduino endpoints with status "Enabled"
curl -v -H "Authorization: Bearer YourAuthenticationToken" "https://cdn.emnify.net/api/v1/endpoint?q=status:0,name:arduino"

If filtering is applied the header contains:

  • X-Filter - filter criteria

Sorting

Sorting criteria will be included in the request URL as {sort} parameter as a comma separated list of sorting properties. The default sort order is ascending. Descending order is specified with - (dash)

# Sort endpoints by name (descending) and status
curl -v -H "Authorization: Bearer YourAuthenticationToken" "https://cdn.emnify.net/api/v1/endpoint?sort=-name,status"

If Sorting is applied the header contains:

  • X-Sort - sort criteria

Code Sample For Simple API Access (JavaScript)

Example call to toggle the state of an endpoint in AngularJS using Restangular library.

function toggleStatus(endpointId){
  // Retrieve an endpoint to be updated
  Restangular.one('endpoint', endpointId).get().then(function(endpoint){

    // Endpoint status is retrieved as an object {id: 0, description: "Enabled"}
    // and should be set as an object i.e. {id: 1} w/o description
    // Available statuses:
    // 0 ~ Enabled
    // 1 ~ Disabled
    var newStatus = endpoint.status.id == 1 ? {id: 0} : {id: 1};

    // PATCH (update) endpoint status
    Restangular.one('endpoint', endpointId).patch({status: newStatus})
      // Upon successful update, reload the endpoint list
      .then(function(){
        $scope.loadEndpointList();
      });

  });
}

Link to this sample in Plunker

Root Entry 

Root entry point for EMnify Rest API. Provides the list of available entry points.

EMnify Rest API Root 

Retrieve Entry Points
/api/v1
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "method": "GET",
    "uri": "/api/v1/endpoint/:id",
    "description": "Retrieve single Endpoint details by id"
  },
  {
    "method": "POST",
    "uri": "/api/v1/endpoint",
    "description": "Create new Endpoint"
  },
  {
    "method": "GET",
    "uri": "/api/v1/endpoint/status",
    "description": "List of available Endpoint Statuses"
  }
]

Authentication 

The initial authentication against the API is done by providing username/password credentials to retrieve an authentication token.

In order to support efficient M2M communications, an authenticated user may use the API to retrieve a long-lived token (hereinafter referred to as ‘application token’) that can be used instead of user credentials in the authentication request. It is highly recommended to use application tokens for M2M communications instead of authentications tokens.

The authentication token is then sent in all subsequent requests to the API in the ‘Authorization’ header. The token can be stored in-memory for the duration of the user session, or in local token store.

This is a public (unauthenticated) service which does not require (and ignores) authentication tokens.

Authentication for Users

The authentication service takes as input a user name and a password and authenticates a user with his credentials. Upon successful authentication, the service returns an authentication token and a refresh token. The authentication token will be valid for 240 minutes and the refresh token is valid for 350 minutes, but it can only be used once and loses its validity if the user logs in from somewhere else (different web client). When the authentication token has expired the user will need to re-authenticate (either with the refresh token or with the user credentials) in order to get a new authentication token. If both tokens have expired, the user will need to perform the initial authentication again.

Authentication for Applications

When the authentication service is used with an application token instead of user credentials, it returns an authentication token only. The authentication token will be valid for 240 minutes.

After expiration, the application will need to re-authenticate by providing the application token again. The application token is valid until it expires or is revoked by an authorized user of the organisation. The expiration time of an application token is configurable during creation.

Authentication 

User/Application Authentication
/api/v1/authenticate

User Authentication

Authenticates user credentials and returns an auth token and a refresh token. The auth token is used for the requests to the API, but has a short validity period of 240 minutes. The refresh token can be used to gain a new auth token without providing the user credentials again. The refresh token is valid for 350 minutes.

Provided fields:

  • username (String required)

  • password (String required) - User password

  • fingerprint (String optional) - “fingerprint” of a trusted device (if this device is already trusted, no MFA code needs to be provided)

OR

  • refresh_token (String required) - refresh_token received after a successful authentication

Returns:

  • auth_token(String)

  • refresh_token(String) - only with username and password or refresh_token

User Authentication with Multi-factor Authentication

If a user has multi-factor authentication enabled for his account, then Authentication is performed in 2 steps

  • The initial submission of the credentials (username/password) gets a mfa_token in the response instead of auth_token and refresh_token.

  • The second “authenticate” request with this mfa_token and the generated OTP code for the multi-factor authentication will then receive the auth_token and refresh_token in the response.

Provided fields for 2nd step:

  • mfa_token (String required) - JWT returned from the 1st step

  • code (String required) - “One-Time Password” code

  • trusted_device (Object optional) - details of a “trusted_device” for which the second MFA step will be skipped in the future

NOTES:

  • If the “fingerprint” of a trusted device is included in the first authentication request and it matches the “fingerprint” of a device trusted for this user, then the auth_token and refresh_token are returned at once; if this device is already trusted, no MFA code needs to be provided in a second step.

  • If the second authentication request is successful and includes the details of a “trusted_device” (fingerprint, operating system and browser), then these data will be stored and the “fingerprint” may be used later to authenticate in one step, as just explained in the previous note.

Application Authentication

Authenticates with the application token and returns an auth token. The auth token is used for the requests to the API, but has a short validity period. When it expires, the application token must be used again to gain a new auth token.
An application may optionally authenticate as a child organisation, by specifying the target organisation in the JSON request.

Provided fields:

  • application_token (String required) - application_token received after a successful application token creation

  • organisation (Object optional) | id Number

Returns:

  • auth_token(String)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "username": "user@domain.com",
  "password": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
}
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "refresh_token": "GciOiJIUzI1NiIsInR5cCI6I"
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "username": "userwithmfa@domain.com",
  "password": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12"
}
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "username": "userwithmfa@domain.com",
  "password": "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12",
  "fingerprint": "00000000-54b3-e7c7-0000-000046bffd97"
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eysdfhaksjdhf"
}
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "code": "312312",
  "trusted_device": {
    "fingerprint": "00000000-54b3-e7c7-0000-000046bffd97",
    "operating_system": "Ubuntu 16.04.2 LTS (Xenial)",
    "browser": "Mozilla Firefox"
  }
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "auth_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2V...",
  "refresh_token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJ1c2V..."
}
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "application_token": "8Y8knYSkeyYV23kd86qb1Vwt6PJGPYetg..."
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
  • Response  401
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "application_token": "8Y8knYSkeyYV23kd86qb1Vwt6PJGPYetg...",
  "organisation": {
    "id": 1234
  }
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "auth_token": "eyXhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjEzO..."
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Organisation with Id '1234' not found."
}

MFA Key Creation 

This section describes the available API services for managing Multi-Factor Authentication Keys.

Create MFA Key
/api/v1/user/mfa

Generate and store a MFA key for the requesting user. The MFA key is in status activation pending after this call and must be activated through a separat call (see following).

You must provide following fields with this request:

  • type (Object required) | id Number

  • password (String required) - User password

Description of MFA key properties

Here is the description of MFA key object

Name Type Description
id Integer Unique ID of this MFA key
status Object ID (Integer) - Id of status of this MFA key
description (String) - description of the status
type Object ID (Integer) - Id of type of this MFA key
description (String) - description of the type
secret_key String Secret key (encoded in Base32) for this MFA key, will be displayed only on creation
otpauth String Secret key as a URI encoded for QR codes, will be displayed only on creation
creation_date Timestamp Timestamp when this MFA key was created - type: ISO 8601 timestamp format
activation_date Timestamp Timestamp when this MFA key was activated - type: ISO 8601 timestamp format

The following table lists errors that may occur as a result of this call:

HTTP
Status		 Error
Code		 Error
Token		 Description
and parameters		 Scenario
401 - - Unauthorized : the given password was invalid
409 1405 Duplicated MFA already activated Cannot create new MFA key if there is already one active.
422 1400 InputValidationFailed InvalidValue MFA key - Type is invalid
422 1400 InputValidationFailed Required MFA key - password is required / type is required
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "type": {
    "id": 0
  },
  "password": "2f2f2f2f2f2f2f2f2f2f2f2f"
}
  • Response  200
  • Body
    {
  "id": 44,
  "status": {
    "id": 0,
    "description": "Activation Pending"
  },
  "type": {
    "id": 0,
    "description": "Time-Based One-Time Password"
  },
  "secret_key": "YZP7UN4EMN6LK2UYYDCTBNH4ZVXVEJ7C",
  "otpauth": "otpauth://totp/EMnify:user@org.com?secret=YZP7UN4EMN6LK2UYYDCTBNH4ZVXVEJ7C&issuer=EMnify&digits=6&period=30",
  "creation_date": "2017-02-03T15:04:03+0100"
}
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "MFA already activated"
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "InputValidationFailed",
  "errors": [
    {
      "error_code": 1408,
      "error_token": "InvalidValue",
      "message": "MFA Key - Type is invalid: 1."
    }
  ]
}

MFA Key Activation 

Activate MFA Key
/api/v1/user/mfa/{id}

Activate the MFA key of the requesting user.

You must provide following JSON fields in this request:

  • status (Object required) | id Number (use 1 for “ACTIVE” status)

  • code (String required) the 6-digit “time-based one-time password” (TOTP) generated with this MFA key for the current Time-Step

  • Parameters
  • id
    number (required) 

    Key ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "status": {
    "id": 1
  },
  "code": "123456"
}
  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "MFA Key with Id '27' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "MFA already activated"
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "MFA key validation error: Code did not match!"
}

MFA Key Deletion 

Delete MFA Key
/api/v1/user/{userId}/mfa/{keyId}

Delete a MFA key for a given user.
An own MFA key can also be deleted with a call to /api/v1/user/my/mfa/{keyId}

  • Parameters
  • userId
    number (required) 

    User ID

    keyId
    number (required) 

    Key ID

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "MFA Key with id '1234' not found"
}

MFA Key Status 

MFA Key Status Lookup
/api/v1/user/mfa/status

Retrieve a list of possible MFA Key statuses.

  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Activation Pending"
  },
  {
    "id": 1,
    "description": "Active"
  }
]

MFA Key Type 

MFA Key Type Lookup
/api/v1/user/mfa/type

Retrieve a list of possible MFA Key types.

  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Time-Based One-Time Password"
  }
]

Trusted Devices Collection 

List of trusted devices
/api/v1/user/{userId}/mfa/trusted_device

Returns the list of trusted devices for a given user.
The list of one’s own trusted devices can also be retrieved with a call to either /api/v1/user/my/mfa/trusted_device or /api/v1/user/mfa/trusted_device

  • Parameters
  • userId
    number (required) 

    User ID

  • Response  200
  • Body
    [
  {
    "id": 16,
    "operating_system": "Ubuntu 16.04.2 LTS (Xenial)",
    "browser": "Mozilla Firefox",
    "activation_date": "2016-02-29T16:04:20+0000"
  },
  {
    "id": 71,
    "operating_system": "Android 7.1 Nougat",
    "browser": "Dolphin",
    "activation_date": "2016-10-04T07:01:01+0000"
  }
]
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "User with Id '1234' not found."
}

Single Trusted Device Operations 

Remove trusted device
/api/v1/user/{userId}/mfa/trusted_device/{deviceId}

Deletes a trusted device.

Removing one’s own trusted device can also be performed at either
/api/v1/user/my/mfa/trusted_device/{deviceId} or /api/v1/user/mfa/trusted_device/{deviceId}

  • Parameters
  • userId
    number (required) 

    User ID

    deviceId
    number (required) 

    Device ID

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Trusted Device with Id '9999' not found"
}

Application Tokens 

This section describes the available API services for managing the application token resource.

Application Token Collection 

List of Application Tokens
/api/v1/application_token

Returns the list of application tokens for the organisation of the requesting user.

  • Response  200
  • Body
    [
  {
    "id": 1,
    "description": "App Test Token",
    "created": "2015-04-28T12:25:44+0000",
    "status": {
      "id": 0,
      "description": "Activated"
    },
    "expiry_date": "2016-02-02T23:00:00+0000",
    "ip": "10.88.0.139/32",
    "creator": {
      "id": 6,
      "name": "Master User",
      "username": "user6@org2"
    }
  },
  {
    "id": 2,
    "description": "Revoked App Token",
    "created": "2015-01-11T12:26:26+0000",
    "status": {
      "id": 1,
      "description": "Revoked"
    },
    "creator": {
      "id": 6,
      "name": "Master User",
      "username": "user6@org2"
    }
  }
]
Create Application Token
/api/v1/application_token

Creates a new application token.

ID must not be specified, as it is auto-generated and returned in case of a successful JSON response.

You can provide following fields with this request:

  • Description (String, optional)

  • Expiry date with optional time + time zone (String, optional)

  • IP Address in CIDR notation (String, optional)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "description": "My Application Token",
  "expiry_date": "2020-12-31T23:59:59+01:00",
  "ip": "10.203.23.78/32"
}
  • Response  200
  • Headers
    Location: https://cdn.emnify.net/api/v1/application_token/42
    Body
    {
  "application_token": "KAOp24TuMgjO2FpZmZ3ZFjSqpk7ea_mY8H2daMlMXF-lRbmMzLeQwSEX67-NFczI3GgHcHpCKTfAw"
}
  • Response  422
  • Body
    {
  "error_code": 1403,
  "error_token": "InvalidFormat",
  "message": "Application Token - IP has invalid format: Expecting IP Address in CIDR Notation."
}

Single Application Token Operations 

Update Application Token
/api/v1/application_token/{id}

Change the description of the token or revoke it.

Provided fields:

  • description (String, optional)

  • status (Object, optional)

  • Parameters
  • id
    number (required) 

    application token ID

  • Request
  • Body
    {
  "description": "new description",
  "status": {
    "id": 1
  }
}
  • Response  204

Endpoint 

This section describes available API services for managing endpoint resources. API provides services to retrieve the collection of endpoints with paging, filtering and sorting options. It also provides services for single endpoint retrieval and CRUD operations via POST, PATCH and DELETE actions.

Below is the sample endpoint in JSON representation. Apart from own data, the object contains embedded objects:

  • service_profile

  • tariff_profile

  • sim and

  • runtime_data

{
  "id": 1,
  "name": "arduino01",
  "tags": "arduino, meter, temp",
  "created": "2014-08-01T08:47:00+00:00",
  "last_updated": "2016-03-02T15:25:34.000+0000",
  "status": {
    "id": 0,
    "description": "Enabled"
  },
  "service_profile": {
    "id": 1,
    "name": "Smart Meter"
  },
  "tariff_profile": {
    "id": 3,
    "name": "Domestic only"
  },
  "sim": {
    "id": 788,
    "iccid": "736826736473829773621",
    "imsi": "901991234567890",
      "msisdn": "+88563748761"
  },
  "imei": "864345678889321",
  "imei_lock": true,
  "ip_address": "10.2.1.1",
  "ip_address_space": {
    "id": 2,
    "ip_address_space": "10.2.0.0/16",
    "ip_address_version": 4
  },
  "runtime_data": {
  "msc": "491790802121",
  "sgsn": "491752345678",
    "sgsn_ip_address": "82.113.96.21"
  }
}

Description of endpoint properties

Here is the description of endpoint object

Name Type Description
id Integer Unique ID of this endpoint
name String Name of endpoint
tags String Assigned Tags
created Timestamp Timestamp when this endpoint was created (ISO 8601 timestamp format)
last_updated Timestamp Timestamp when this endpoint was updated last time (ISO 8601 timestamp format)
status Object ID (Integer) - ID of status this endpoint
description (String) - description of meaning of the status
service_profile Object ID (Integer) - ID of assigned service profile
name (String) - name of the service profile
tariff_profile Object ID (Integer) - ID of assigned tariff profile
name (String) - name of the tariff profile
image String File name of image to display for this endpoint
sim Object ID (Integer) - ID of SIM card
iccid (String) - ICCID of SIM card
imsi (String) - currently active IMSI on this SIM card
msisdn (String) - MSISDN assigned to this SIM card
imei String IMEI number of device in use
imei_lock boolean Is the endpoint locked to the current IMEI or not
ip_address String Configured IP address
ip_address_space Object ID (Integer) - ID of assigned ip address space
ip_address_space (String) - subnet of the IP address space
ip_address_version (Interger) - IP version for this address space, e.g. 4 or 6
runtime_data Object msc (String) - global title of MSC this endpoint is connected to
sgsn (String) - global title of the serving SGSN
sgsn_ip_address (String) - IP of SGSN currently serving this endpoint

Endpoint Collection 

Endpoint collection service.

List of Endpoints
/api/v1/endpoint?{q}{page}{per_page}{sort}

Returns the list of endpoints, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    String (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields,
    id,
    status,
    service_profile,
    tariff_profile,
    last_updated,
    created,
    name,
    tags,
    ip_address,
    imei,
    sim,
    iccid.

    Example q=status:2,service_profile:1

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields,
    id,
    status,
    service_profile,
    tariff_profile,
    last_updated,
    created,
    name,
    tags,
    ip_address,
    imei.

    Example sort=-status,id
    Sort by status descending and id ascending

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Link: <https://cdn.emnify.net/api/v1/endpoint?q=status:1,service_profile:1&per_page=100&sort=-status,id>; rel="first", <https://cdn.emnify.net/api/v1/endpoint?q=status:1,service_profile:1&page=5&per_page=100&sort=-status,id>; rel="prev", <https://cdn.emnify.net/api/v1/endpoint?q=status:1,service_profile:1&page=7&per_page=100&sort=-status,id>; rel="next", <https://cdn.emnify.net/api/v1/endpoint?q=status:1,service_profile:1&page=34&per_page=100&sort=-status,id>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: status:2,service_profile:1
    X-Sort: -status,id
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "id": 1,
    "name": "arduino01",
    "tags": "arduino, meter, temp",
    "created": "2014-08-01T08:47:00+00:00",
    "last_updated": "2016-02-29T14:02:47.000+0000",
    "status": {
      "id": 1,
      "description": "Disabled"
    },
    "service_profile": {
      "id": 1,
      "name": "Smart Meter"
    },
    "tariff_profile": {
      "id": 3,
      "name": "Domestic only"
    },
    "sim": {
      "id": 788,
      "iccid": "736826736473829773621",
      "imsi": "901991234567890",
      "msisdn": "+88563748761"
    },
    "imei": "864345678889321",
    "imei_lock": true,
    "ip_address": "10.203.23.75",
    "ip_address_space": {
      "id": 2
    }
  },
  {
    "id": 2,
    "name": "arduino02",
    "tags": "arduino, meter, temp",
    "created": "2014-08-19T16:47:00+00:00",
    "status": {
      "id": 1,
      "description": "Disabled"
    },
    "service_profile": {
      "id": 1,
      "name": "Smart Meter"
    },
    "tariff_profile": {
      "id": 3,
      "name": "Domestic only"
    },
    "sim": {
      "id": 789,
      "iccid": "736826736473829773622",
      "imsi": "901991234567891",
      "msisdn": "+88563748762"
    },
    "imei": "864345678897829",
    "imei_lock": false,
    "ip_address": "10.203.23.76",
    "ip_address_space": {
      "id": 2
    }
  }
]

Endpoint Creation 

Create Endpoint
/api/v1/endpoint

Creates the specified endpoint.

ID must not be specified, neither in query String, nor in JSON payload. If the “activate” flag in the SIM object is not contained in JSON or if it is set to true, then the sim assigned on endpoint creation will be automatically activated (if not already active).

You can provide following fields with this request:

  • Name (String required)

  • Tags (String optional)

  • Status (Object required)

  • Service profile (Object required)

  • Tariff profile (Object required)

  • IP address (String optional)

  • IP address space (Object optional if IP address is missing, mandatory when IP address is set)

  • SIM (Object optional) | id (number required) of the SIM to be assigned to this endpoint | activate (Boolean optional, default true)

  • Imei (String optional)

  • Imei_Lock (Boolean optional)

The following table lists errors that may occur as a result of this call:

HTTP
Status		 Error
Code		 Error
Token		 Description
and parameters		 Scenario
404 1601 Unavailable No IP Address available. All IP address in given IP address space are in use.
404 1401 InvalidReference IP Address Space with Id ‘42’ not found. IP address space chosen which does not exist or does not belong to organisation.
409 2101 Cannot activate No SIM Endpoint status was set to Active, but there was no SIM assigned.
409 1405 Duplicated IP address - 1.2.3.4 already assigned The specified IP is already assigned to another endpoint.
422 1400 InputValidationFailed InvalidValue IP address is invalid / IP address space is invalid.
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "arduino01",
  "tags": "arduino, meter, temp",
  "status": {
    "id": 0
  },
  "service_profile": {
    "id": 2
  },
  "tariff_profile": {
    "id": 3
  },
  "ip_address": "10.203.23.78",
  "ip_address_space": {
    "id": 1
  },
  "sim": {
    "id": 1,
    "activate": true
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/endpoint/42
  • Response  404
  • Body
    {
  "error_code": 1601,
  "error_token": "Unavailable",
  "message": "No IP Address available."
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "IP Address Space with Id '27' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "IP Address - fd:0:0:0:0:0:0:1 already assigned."
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "InputValidationFailed",
  "errors": [
    {
      "error_code": 1404,
      "error_token": "OutOfRange",
      "message": "Endpoint - IP Address out of range."
    }
  ]
}

Single Endpoint Operations 

Retrieve Single Endpoint
/api/v1/endpoint/{id}

Retrieves an endpoint with a given id.

  • Parameters
  • id
    number (required) 

    Endpoint ID

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Body
    {
  "id": 1,
  "name": "arduino01",
  "tags": "arduino, meter, temp",
  "created": "2014-08-01T08:47:00+00:00",
  "last_updated": "2016-02-29T14:02:47.000+0000",
  "status": {
    "id": 0,
    "description": "Enabled"
  },
  "service_profile": {
    "id": 1,
    "name": "Smart Meter"
  },
  "tariff_profile": {
    "id": 3,
    "name": "Domestic only"
  },
  "sim": {
    "id": 788,
    "iccid": "736826736473829773621",
    "imsi": "901991234567890",
    "msisdn": "+88563748761"
  },
  "imei": "864345678889321",
  "imei_lock": false,
  "ip_address": "10.203.23.75",
  "ip_address_space": {
    "id": 2,
    "ip_address_space": "10.203.23.0/24",
    "ip_address_version": 4
  },
  "runtime_data": {
    "msc": "491790802121",
    "sgsn": "491752345678",
    "sgsn_ip_address": "82.113.96.21"
  }
}
Delete Endpoint
/api/v1/endpoint/{id}

Deletes an endpoint and all its child entities.

  • Parameters
  • id
    number (required) 

    endpoint ID

  • Response  204
Update Endpoint
/api/v1/endpoint/{id}

Update endpoint.

You can provide following fields with this request:

  • Name (String optional)

  • Tags (String optional)

  • Status (Object optional)

  • Service profile (Object optional)

  • Tariff profile (Object optional)

  • IP address (String optional)

  • IP address space (Object optional if IP address is missing, mandatory when IP address is set)

  • SIM (Object optional)

  • Imei (String optional)

  • Imei_Lock (Boolean optional)

The following table lists errors that may occur as a result of this call:

HTTP
Status		 Error
Code		 Error
Token		 Description
and parameters		 Scenario
404 1601 Unavailable No IP Address available. All IP address in given IP address space are in use.
404 1401 InvalidReference IP Address Space with Id ‘42’ not found. IP address space chosen which does not exist or does not belong to organisation
409 2101 Cannot activate No SIM Endpoint status was set to Active, but there was no SIM assigned.
409 1405 Duplicated IP address - 1.2.3.4 already assigned The specified IP is already assigned to another endpoint.
422 1400 InputValidationFailed InvalidValue IP address is invalid / IP address space is invalid.
  • Parameters
  • id
    number (required) 

    endpoint ID

  • Request
  • Body
    {
  "tags": "tag1, tag2, tag3",
  "status": {
    "id": 1
  },
  "service_profile": {
    "id": 1
  },
  "tariff_profile": {
    "id": 1
  },
  "ip_address": "127.0.0.1",
  "ip_address_space": {
    "id": 2
  },
  "sim": {
    "id": 1
  },
  "imei": "123456789112345",
  "imei_lock": true
}
  • Response  204

Traffic Limit Collection Assigned to an Endpoint 

Traffic limits can be assigned to an endpoint either indirectly via service profile or directly.

Retrieve Endpoint Traffic Limits
/api/v1/endpoint/{id}/traffic_limit
  • Parameters
  • id
    number (required) 

    endpoint ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 123,
    "service": 11,
    "volume": 64,
    "period": {
      "id": 33,
      "time_units": 5,
      "unit": "Days"
    }
  },
  {
    "id": 234,
    "service": 12,
    "volume": 128,
    "period": {
      "id": 35,
      "time_units": 1,
      "unit": "Months"
    }
  }
]

Managing Traffic Limit Collection Assigned to an Endpoint 

Assign Endpoint Traffic Limits
/api/v1/endpoint/{endpointId}/traffic_limit/{trafficLimitId}

Traffic limits can be assigned directly to an endpoint.

  • Parameters
  • endpointId
    number (required) 

    endpoint ID

    trafficLimitId
    number (required) 

    ID of a traffic_limit to be assigned

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Body
    {
  "id": 1,
  "name": "arduino01",
  "tags": "arduino, meter, temp",
  "created": "2014-08-01T08:47:00+00:00",
  "last_updated": "2016-02-29T14:02:47.000+0000",
  "status": {
    "id": 0,
    "description": "Enabled"
  },
  "service_profile": {
    "id": 1,
    "name": "Smart Meter"
  },
  "tariff_profile": {
    "id": 3,
    "name": "Domestic only"
  },
  "sim": {
    "id": 788,
    "iccid": "736826736473829773621",
    "imsi": "901991234567890",
    "msisdn": "+88563748761"
  },
  "imei": "864345678889321",
  "imei_lock": false,
  "ip_address": "10.203.23.75",
  "ip_address_space": {
    "id": 2,
    "ip_address_space": "10.203.23.0/24",
    "ip_address_version": 4
  },
  "runtime_data": {
    "msc": "491790802121",
    "sgsn": "491752345678",
    "sgsn_ip_address": "82.113.96.21"
  }
}
Remove an Associated Traffic Limit
/api/v1/endpoint/{endpointId}/traffic_limit/{trafficLimitId}

Delete a single traffic limit association.

  • Parameters
  • endpointId
    number (required) 

    endpoint ID

    trafficLimitId
    number (required) 

    ID of a traffic_limit to be assigned

  • Response  204

Accessing Endpoint Connectivity Status 

Retrieve details about current connectivity status of endpoint.

Retrieve Endpoint Connectivity Status
/api/v1/endpoint/{id}/connectivity
  • Response  200
  • Body
    {
  "status": {
    "description": "ONLINE"
  },
  "location": {
    "iccid": "8988303009999999999",
    "imsi": "901439999999999",
    "last_updated": "2015-12-03 07:06:04",
    "last_updated_gprs": "2015-11-30 14:55:35",
    "sgsn_number": "491770695700",
    "vlr_number": "491770940000",
    "msc": "491770940000",
    "operator": {
      "id": 4,
      "name": "EPlus",
      "country": {
        "id": 74,
        "name": "Germany"
      }
    },
    "country": {
      "country_id": "74",
      "name": "Germany",
      "country_code": "49",
      "mcc": "262",
      "iso_code": "de"
    },
    "sgsn_ip_address": "212.23.107.88"
  },
  "pdp_context": {
    "pdp_context_id": "92415",
    "endpoint_id": "166",
    "tariff_profile_id": "35",
    "tariff_id": "54",
    "ratezone_id": "70",
    "organisation_id": "2",
    "imsi_id": "627",
    "imsi": "901439999999999",
    "sim_id": "625",
    "teid_data_plane": "7116",
    "teid_control_plane": "7116",
    "gtp_version": "1",
    "nsapi": "5",
    "sgsn_control_plane_ip_address": "212.23.107.89",
    "sgsn_data_plane_ip_address": "212.23.107.89",
    "ggsn_control_plane_ip_address": "185.57.216.35",
    "ggsn_data_plane_ip_address": "185.57.216.35",
    "created": "2015-12-04 08:12:02",
    "mcc": "262",
    "mnc": "03",
    "operator_id": "4",
    "lac": "40217",
    "ci": null,
    "sac": "42937",
    "rac": null,
    "ue_ip_address": "10.199.5.223",
    "imeisv": "3526510721968301",
    "rat_type": {
      "rat_type_id": "1",
      "description": "3G"
    },
    "duration": "00:00:04"
  },
  "services": [
    "GPRS"
  ]
}

Accessing Endpoint Billing 

Not yet implemented.

Retrieve Endpoint Billing
/api/v1/endpoint/{id}/billing
  • Response  200

Accessing Endpoint Statistics 

Retrieve usage and costs statistics for current/last month/hour.

Retrieve Endpoint Statistics
/api/v1/endpoint/{id}/stats
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "last_month": {
    "data": {
      "endpoint_id": "166",
      "month": "2015-11-01",
      "volume": "29.166235",
      "volume_tx": "5.577229",
      "volume_rx": "23.589006",
      "traffic_type_id": "5",
      "last_updated": "2015-11-30 14:56:25",
      "cost": "6.1048393500",
      "currency_id": "1",
      "id": 311,
      "traffic_type": {
        "description": "Data",
        "unit": "MB",
        "id": 5
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    },
    "sms": {
      "endpoint_id": "166",
      "month": "2015-11-01",
      "volume": "51.000000",
      "volume_tx": "36.000000",
      "volume_rx": "15.000000",
      "traffic_type_id": "6",
      "last_updated": "2015-11-26 10:52:42",
      "cost": "3.3200000000",
      "currency_id": "1",
      "id": 312,
      "traffic_type": {
        "description": "SMS",
        "unit": "SMS",
        "id": 6
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    }
  },
  "current_month": {
    "data": {
      "endpoint_id": "166",
      "month": "2015-12-01",
      "volume": "0.848157",
      "volume_tx": "0.172846",
      "volume_rx": "0.675311",
      "traffic_type_id": "5",
      "last_updated": "2015-12-01 15:12:53",
      "cost": "0.2120392500",
      "currency_id": "1",
      "id": 435,
      "traffic_type": {
        "description": "Data",
        "unit": "MB",
        "id": 5
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    },
    "sms": {
      "endpoint_id": "166",
      "month": "2015-12-01",
      "volume": "3.000000",
      "volume_tx": "2.000000",
      "volume_rx": "1.000000",
      "traffic_type_id": "6",
      "last_updated": "2015-12-01 14:20:42",
      "cost": "0.1700000000",
      "currency_id": "1",
      "id": 439,
      "traffic_type": {
        "description": "SMS",
        "unit": "SMS",
        "id": 6
      },
      "currency": {
        "code": "EUR",
        "symbol": "€",
        "id": 1
      }
    }
  },
  "last_hour": {
    "data": {
      "rx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ],
      "tx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ]
    },
    "sms": {
      "rx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ],
      "tx": [
        [
          "06:38",
          0
        ],
        [
          "06:39",
          0
        ],
        [
          "06:40",
          0
        ],
        [
          "06:41",
          0
        ],
        [
          "06:42",
          0
        ],
        [
          "06:43",
          0
        ],
        [
          "06:44",
          0
        ],
        [
          "06:45",
          0
        ],
        [
          "06:46",
          0
        ],
        [
          "06:47",
          0
        ],
        [
          "06:48",
          0
        ],
        [
          "06:49",
          0
        ],
        [
          "06:50",
          0
        ],
        [
          "06:51",
          0
        ],
        [
          "06:52",
          0
        ],
        [
          "06:53",
          0
        ],
        [
          "06:54",
          0
        ],
        [
          "06:55",
          0
        ],
        [
          "06:56",
          0
        ],
        [
          "06:57",
          0
        ],
        [
          "06:58",
          0
        ],
        [
          "06:59",
          0
        ],
        [
          "07:00",
          0
        ],
        [
          "07:01",
          0
        ],
        [
          "07:02",
          0
        ],
        [
          "07:03",
          0
        ],
        [
          "07:04",
          0
        ],
        [
          "07:05",
          0
        ],
        [
          "07:06",
          0
        ],
        [
          "07:07",
          0
        ],
        [
          "07:08",
          0
        ],
        [
          "07:09",
          0
        ],
        [
          "07:10",
          0
        ],
        [
          "07:11",
          0
        ],
        [
          "07:12",
          0
        ],
        [
          "07:13",
          0
        ],
        [
          "07:14",
          0
        ],
        [
          "07:15",
          0
        ],
        [
          "07:16",
          0
        ],
        [
          "07:17",
          0
        ],
        [
          "07:18",
          0
        ],
        [
          "07:19",
          0
        ],
        [
          "07:20",
          0
        ],
        [
          "07:21",
          0
        ],
        [
          "07:22",
          0
        ],
        [
          "07:23",
          0
        ],
        [
          "07:24",
          0
        ],
        [
          "07:25",
          0
        ],
        [
          "07:26",
          0
        ],
        [
          "07:27",
          0
        ],
        [
          "07:28",
          0
        ],
        [
          "07:29",
          0
        ],
        [
          "07:30",
          0
        ],
        [
          "07:31",
          0
        ],
        [
          "07:32",
          0
        ],
        [
          "07:33",
          0
        ],
        [
          "07:34",
          0
        ],
        [
          "07:35",
          0
        ],
        [
          "07:36",
          0
        ]
      ]
    }
  }
}

Endpoint Status 

List of All Available Endpoint Statuses
/api/v1/endpoint/status
  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Enabled"
  },
  {
    "id": 1,
    "description": "Disabled"
  },
  {
    "id": 2,
    "description": "Deleted"
  }
]

SMS 

SMS collection service.

(alternatively to the RestAPI it is also possible to exchange SMS with our SMSC via SMPP)

List of SMS
/api/v1/endpoint/{id}/sms

Returns the list of SMS send and received by this endpoint.

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Body
    [
  {
    "submit_date": "2015-10-05 13:56:59",
    "delivery_date": "2015-10-05 13:56:59",
    "expiry_date": "2015-10-06 13:56:59",
    "final_date": "2015-10-05 13:57:03",
    "retry_date": null,
    "last_delivery_attempt": "2015-10-05 13:57:00",
    "retry_count": "0",
    "gsm_map_error": null,
    "dcs": 0,
    "pid": 0,
    "source_address": "1234567890",
    "endpoint": {
      "id": 166,
      "name": "Your Endpoint"
    },
    "sim_id": "625",
    "iccid": "8988303000000000851",
    "msisdn": "883XXXXXXXXXXXX",
    "imsi": "901XXXXXXXXXXXX",
    "msc": "491600190000",
    "udh": "",
    "payload": "test",
    "id": 590,
    "status": {
      "description": "DELIVERED",
      "id": 4
    },
    "sms_type": {
      "description": "MT",
      "id": 1
    },
    "source_address_type": {
      "description": "National",
      "id": 161
    }
  },
  {
    "submit_date": "2015-09-29 07:33:15",
    "delivery_date": "2015-09-29 07:33:15",
    "expiry_date": "2015-09-30 07:33:15",
    "final_date": "2015-09-29 07:33:18",
    "retry_date": null,
    "last_delivery_attempt": "2015-09-29 07:33:15",
    "retry_count": "0",
    "gsm_map_error": null,
    "dcs": 0,
    "pid": 0,
    "source_address": "1234",
    "endpoint": {
      "id": 166,
      "name": "Your Endpoint"
    },
    "sim_id": "625",
    "iccid": "8988303000000000851",
    "msisdn": "883XXXXXXXXXXXX",
    "imsi": "901XXXXXXXXXXXX",
    "msc": "491770940000",
    "udh": "",
    "payload": "test",
    "id": 589,
    "status": {
      "description": "DELIVERED",
      "id": 4
    },
    "sms_type": {
      "description": "MT",
      "id": 1
    },
    "source_address_type": {
      "description": "National",
      "id": 161
    }
  },
  {
    "submit_date": "2015-09-21 06:22:03",
    "delivery_date": "2015-09-21 06:22:03",
    "expiry_date": "2015-09-22 06:22:03",
    "final_date": "2015-09-21 06:22:07",
    "retry_date": null,
    "last_delivery_attempt": "2015-09-21 06:22:04",
    "retry_count": "0",
    "gsm_map_error": null,
    "dcs": 0,
    "pid": 0,
    "source_address": "1234",
    "endpoint": {
      "id": 166,
      "name": "Your Endpoint"
    },
    "sim_id": "625",
    "iccid": "8988303000000000851",
    "msisdn": "883XXXXXXXXXXXX",
    "imsi": "901XXXXXXXXXXXX",
    "msc": "491770940000",
    "udh": "",
    "payload": "test",
    "id": 577,
    "status": {
      "description": "DELIVERED",
      "id": 4
    },
    "sms_type": {
      "description": "MT",
      "id": 1
    },
    "source_address_type": {
      "description": "National",
      "id": 161
    }
  }
]
Submit MT-SMS
/api/v1/endpoint/{id}/sms

Submit MT-SMS to specified endpoint.

You can provide following fields with this request:

Name Type Description
payload String required Message text to be send, UTF-8 encoded
source_address String optional Source address of SMS: MSISDN, short code or alphanumeric String
source_address_type Object optional Specify type of source address
expiry_date Date optional Expiry date
udh String optional User Data Header encoded has hex-String
dcs Integer optional Data Coding Scheme
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "source_address": "12345689",
  "payload": "This is the message text"
}
  • Response  201

Single SMS Operations 

Single SMS service.

Get details of SMS
/api/v1/endpoint/{endpoint_id}/sms/{sms_id}

Returns details about the SMS.

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Body
    {
  "submit_date": "2015-10-05 13:56:59",
  "delivery_date": "2015-10-05 13:56:59",
  "expiry_date": "2015-10-06 13:56:59",
  "final_date": "2015-10-05 13:57:03",
  "retry_date": null,
  "last_delivery_attempt": "2015-10-05 13:57:00",
  "retry_count": "0",
  "gsm_map_error": null,
  "dcs": 0,
  "pid": 0,
  "source_address": "1234567890",
  "endpoint": {
    "id": 166,
    "name": "Your Endpoint"
  },
  "sim_id": "625",
  "iccid": "8988303000000000851",
  "msisdn": "883XXXXXXXXXXXX",
  "imsi": "901XXXXXXXXXXXX",
  "msc": "491600190000",
  "udh": "",
  "payload": "test",
  "id": 590,
  "status": {
    "description": "DELIVERED",
    "id": 4
  },
  "sms_type": {
    "description": "MT",
    "id": 1
  },
  "source_address_type": {
    "description": "National",
    "id": 161
  }
}
Cancel SMS
/api/v1/endpoint/{endpoint_id}/sms/{sms_id}

Cancel SMS that is buffered for endpoint and not yet delivered.

  • Response  200

Receiving MO-SMS 

The system can dispatch MO-SMS from endpoints towards a configurable URL, in this case the EMnify system will act as an HTTP client and you will need to provide an HTTP server to accept the request.

Please see Service Profile Configuration on how to set up an API Callback URL.

Your server needs to respond with HTTP Code 2XX to accept the request.

EMnify will optional send an JWT to your server based on a secret set up in the corresponding service profile, by verifying the JWT your server can ensure the request is actually coming from EMnify.

Please see https://jwt.io for libraries to work with JWTs.

Receive SMS
/sms_callback_url_on_your_server

Receive Mobile Originated (MO) SMS from endpoint.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 123,
  "endpoint": {
    "id": 1,
    "name": "Your Endpoint"
  },
  "organisation": {
    "id": 4,
    "name": "Your Organisation Name"
  },
  "source_address": "423123454",
  "dest_address": "123456789",
  "payload": "This is the message text",
  "dcs": 0,
  "pid": 0,
  "subit_date": "2015-10-05 13:56:59"
}
  • Response  200

Events of an Endpoint 

Retrieve Events
/api/v1/endpoint/{endpoint_id}/event?{q}{page}{per_page}{sort}

Returns the list of events, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    number (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, i.e. timestamp, description, source, severity, organisation, endpoint, tags, ip_address, imei, iccid, imsi. Example q=source:2,tags:Monitoring

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields, i.e. timestamp, id.
    Example sort=-timestamp,id
    Sort by timestamp descending and id ascending

  • Response  200
  • Headers
    Link: <https://cdn.emnify.net/api/v1/endpoint/1/event?q=source:2,tags:Monitoring&per_page=100&sort=-severity,timestamp>; rel="first", <https://cdn.emnify.net/api/v1/endpoint/1/event?q=source:2,tags:Monitoring&page=5&per_page=100&sort=-severity,timestamp>; rel="prev", <https://cdn.emnify.net/api/v1/endpoint/1/event?q=source:2,tags:Monitoring&page=7&per_page=100&sort=-severity,timestamp>; rel="next", <https://cdn.emnify.net/api/v1/endpoint/1/event?q=source:2,tags:Monitoring&page=34&per_page=100&sort=-severity,timestamp>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: source:2,tags:Monitoring
    X-Sort: -severity,timestamp
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "timestamp": "2015-07-16 12:07:09",
    "alert": true,
    "description": "PDP Context deleted.",
    "id": 69535,
    "event_type": {
      "description": "Delete PDP Context",
      "id": 4
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 1
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 110
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    }
  }
]

Connectivity Info of an Endpoint 

Description of Connectivity Info Object:

Name Type Description
ussd_info object success (boolean)
error (String) optional if some error occurred
subscriber_info object success (boolean)
error (String) optional if some error occurred
state (String) can be: assumed_idle, camel_busy, net_det_not_reachable, not_provided_from_vlr
not_reachable_reason (String) only set if state is net_det_not_reachable, can be: ms_purged, imsi_detached, restricted_area, not_registered
location (Object)
location Object current_location_retrieved (boolean)
age_of_location (number) age of the location information in minutes
cell_global_id (Object) contains fields for mcc, mnc, lac and cid
request_timestamp Date time of request
reply_timestamp Date time of successful processing the request and sending the reply
Retrieve Connectivity Information
/api/v1/endpoint/{endpoint_id}/connectivity_info?{subscriber}{ussd}

Returns the connectivity information for the specified endpoint.
Possible errors include: “Unknown Subscriber Error”, “Unknown Location Error”, “External Network Error”, “Network Element Not Available Error”, “Network Service Error”, “Data Missing”, “Unexpected Data Value” etc.
Example request: /api/v1/endpoint/123/connectivity_info?subscriber=true&ussd=true

  • Parameters
  • endpoint_id
    number (required) 

    Endpoint ID

    subscriber
    boolean (optional) 

    If true, the Subscriber connectivity info is retrieved. Default is true, i.e. subscriber=true

    ussd
    boolean (optional) 

    If true, the USSD connectivity info is retrieved. Default is false, i.e. ussd=false

  • Response  200
  • Body
    {
  "ussd_info": {
    "success": false,
    "error": "Request Timeout Error"
  },
  "subscriber_info": {
    "success": true,
    "state": "assumed_idle",
    "location": {
      "current_location_retrieved": true,
      "age_of_location": 0,
      "cell_global_id": {
        "mcc": "262",
        "mnc": "01",
        "lac": 23123,
        "cid": 23121
      }
    }
  },
  "request_timestamp": "2015-02-16T13:37:21.415+0000",
  "reply_timestamp": "2015-02-16T13:37:51.823+0000"
}

Operator Blacklist 

Retrieve Operator Blacklist
/api/v1/endpoint/{endpoint_id}/operator_blacklist

Returns a list of blacklisted Operators for the requested Endpoint

  • Parameters
  • endpoint_id
    number (required) 

    Endpoint ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "name": "Telekom",
    "country": {
      "id": 74,
      "name": "Germany",
      "country_code": "49",
      "mcc": "262",
      "iso_code": "de"
    },
    "tapcode": [
      {
        "id": 1,
        "tapcode": "DEUD1"
      }
    ],
    "mnc": [
      {
        "id": 1,
        "mnc": "01"
      }
    ]
  },
  {
    "id": 2,
    "name": "O2",
    "country": {
      "id": 74,
      "name": "Germany",
      "country_code": "49",
      "mcc": "262",
      "iso_code": "de"
    },
    "tapcode": [
      {
        "id": 2,
        "tapcode": "DEUD2"
      }
    ],
    "mnc": [
      {
        "id": 2,
        "mnc": "02"
      }
    ]
  }
]

Managing Operator Blacklist 

Add an Operator to the Blacklist of an Endpoint
/api/v1/endpoint/{epId}/operator_blacklist/{operatorId}

Add Operator to the Blacklist of an Endpoint.

  • Parameters
  • epId
    number (required) 

    ID of the Endpoint

    operatorId
    number (required) 

    ID of the Operator to be removed from blacklist

  • Response  204
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "Operator with Id '155' is already blacklisted on Endpoint with Id '1'."
}
Remove an Operator from the Blacklist of an Endpoint
/api/v1/endpoint/{epId}/operator_blacklist/{operatorId}

Remove Operator from the Blacklist of an Endpoint.

  • Parameters
  • epId
    number (required) 

    ID of the Endpoint

    operatorId
    number (required) 

    ID of the Operator to be removed from blacklist

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Operator with id '155' not found"
}

USSD 

Receiving MO-USSD 

Receive USSD
/ussd_callback_url_on_your_server

Receive MO-USSD from endpoint.

Starting a USSD Dialog

Endpoints can send and receive data to/from your application via USSD by dialing USSD codes in the form of “*xxx#”. The range 100-109 is preconfigured by default, so your endpoint can address different applications on your server.

The system will dispatch MO-USSD requests from endpoints towards a configurable URL, in this case the EMnify system will act as an HTTP client and you will need to provide an HTTP server to accept the request.

Please see Service Profile Configuration on how to set up an API Callback.

Your server needs to respond with HTTP Code 200 to accept the request.

EMnify will optional send an JWT to your server based on a secret set up in the corresponding service profile, by verifying the JWT your server can ensure the request is actually coming from EMnify.

Please see https://jwt.io for libraries to work with JWTs.

USSD Payload

The maximum size of a USSD message is 160 bytes. For GSM 7 Bit encoded messages this gives a limit of 182 characters. If you choose UCS2 encoding you will have a maximum of 80 characters available.

Regardless of the encoding used in the network the payload will always be UTF-8 encoded when transmitted to/from your application along with an indication of the used encoding. The default encoding is GSM 7 Bit.

Continuing a USSD Dialog

After receiving the initial request from the endpoint your application may decide to continue the dialog (“ussd-continue”) by sending back some message and waiting for further input from the endpoint.

Ending a USSD Dialog

Your application may decide to close the dialog after the first request or after multiple messages (“ussd-end”), also in this case a message will be send back to the endpoint and then the dialog will be closed.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "ussd-begin": {
    "endpoint": {
      "id": 1,
      "name": "Your Endpoint"
    },
    "message": {
      "encoding": "default",
      "body": "*101#"
    },
    "session-id": "b5136456-d18d-4605-a79d-8464cc9fabc1"
  }
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "ussd-continue": {
    "message": {
      "encoding": "default",
      "body": "SomeText"
    }
  }
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "ussd-end": {
    "message": {
      "encoding": "default",
      "body": "SomeText"
    }
  }
}

Sending NI-USSD 

Starting a USSD Dialog
/api/v1/endpoint/{id}/ussd

Your application may start a Network-Initiated (NI) USSD Dialog for an endpoint. If the endpoint has an IMSI online (location data is available and valid for one of its IMSIs), then a session-id is generated and returned. This session-id will be used in all subsequent USSD communication between your application and the endpoint.

You must provide following fields with this request:

  • ussd-begin (Object required) containing “type” and “message”

  • type (String required) can be “request” or “notification”

  • message (Object required) including encoding (String optional) e.g. “default” (where default is gsm7) or “ucs2”, body (String required). Depending on the encoding, the maximum length of the body is 164 (default) or 72 (ucs2).

If the USSD Dialog cannot be initiated, possible errors include: “Unknown Subscriber Error”, “Endpoint Not Found”

  • Parameters
  • id
    number (required) 

    Endpoint ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "ussd-begin": {
    "type": "request",
    "message": {
      "encoding": "default",
      "body": "Initial message"
    }
  }
}
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "session-id": "b5136456-d18d-4605-a79d-8464cc9fabc1"
}

Organisation 

Organisation management API.

Organisations are hierarchically organized via parent/child relation with a relation type.

This section describes available API services for managing organisations.

The API provides:

  • CRUD operations via POST, GET, PATCH and DELETE actions

  • services for managing organisation hierarchy

  • services for managing contacts

  • access points for lookup values:

    • organisation status
    • organisation type
    • organisation relation type
    • organisation verification type
    • contact type

Below is a sample organisation in its JSON representation.

{
  "id": 12,
  "name": "Tele17",
  "ext_reference": "",
  "class":{
    "id": 0,
    "description": "Commercial"
  },
  "type": {
    "id": 1,
    "description": "Provider"
  },
  "country": {
    "id": 74,
    "name": "Germany",
    "mcc": "262",
    "country_code": "49",
    "isocode": "de"
  },
  "status": {
    "id": 1,
    "description": "Suspended"
  },
  "relation": {
    "id": 17,
    "type": {
      "id": 0,
      "description": "Customer of"
    }
  },
  "monthly_cost_limit": 1000,
  "currency": {
    "id": 1,
    "code": "EUR",
    "symbol": "€"
  },
  "created": "2015-02-03T00:00:00.000+0000",
  "verification_type": {
    "id": 1,
    "description": "Business registration number"
  },
  "verification": "123456789"
}

Description of organisation properties

Here is the description of organisation object

Name Type Description
id Integer Unique ID of this organisation
name String Name of organisation
class Object id (Integer) - ID of the class of this organisation
description (String) - Description of the class
type Object id (Integer) - ID of the type of this organisation
description (String) - Description of meaning of the type
country Object id (Integer) - ID of the country of this organisation
name (String) - Country name
mcc (String) - mobile country code
country code (String) -
isocode (String) - ISO 3166-1 alpha-2
status Object id (Integer) - ID of status this organisation
description (String) - Description of meaning of the status
relation Object id (Integer) - ID of the relation
type (Object) type of the relation
    description (String) - Description of meaning of the type id
    id (integer) ID of the relation type
ext_reference String Additional information (e.g. customer id)
monthly_cost_limit Integer Amount of spend money when organisation will be blocked
currency Object id (Integer) - ID of the currency
code (String) - Name of the currency
symbol(String) - Symbol of the currency
created Timestamp Timestamp when this organisation was created - Type: ISO 8601 timestamp format
verification_type Object id (Integer) - ID of this verification type
description (String) - Description of the verification type
verification String verification data

Organisation Collection 

Retrieve Organisation List
/api/v1/organisation?{q}{page}{per_page}{sort}

Retrieves a list of the child organisations of your organisation, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    String (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields,
    id,
    status,
    name,
    country,
    ext_reference,
    type.

    Example q=status:0,country:74

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields,
    id,
    status,
    name,
    country,
    ext_reference,
    type,
    created.

    Example sort=-status,id
    Sort by status descending and id ascending

  • Response  200
  • Headers
    Content-Type: application/json
    Link: <https://cdn.emnify.net/api/v1/organisation?q=status:0,country:74&per_page=100&sort=-status,id>; rel="first", <https://cdn.emnify.net/api/v1/organisation?q=status:0,country:74&page=5&per_page=100&sort=-status,id>; rel="prev", <https://cdn.emnify.net/api/v1/organisation?q=status:0,country:74&page=7&per_page=100&sort=-status,id>; rel="next", <https://cdn.emnify.net/api/v1/organisation?q=status:0,country:74&page=34&per_page=100&sort=-status,id>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: status:0,country:74
    X-Sort: -status,id
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "id": 12,
    "name": "Tele17",
    "class": {
      "id": 0,
      "description": "Commercial"
    },
    "type": {
      "id": 1,
      "description": "Provider"
    },
    "country": {
      "id": 74,
      "name": "Germany",
      "mcc": "262",
      "country_code": "49",
      "isocode": "de"
    },
    "status": {
      "id": 0,
      "description": "Enabled"
    },
    "relation": {
      "id": 17,
      "type": {
        "id": 2,
        "description": "Roaming Partner"
      }
    },
    "monthly_cost_limit": 1000,
    "currency": {
      "id": 1,
      "code": "EUR",
      "symbol": "€"
    },
    "created": "2015-02-03T00:00:00.000+0000",
    "verification_type": {
      "id": 1,
      "description": "Business registration number"
    },
    "verification": "123456789"
  },
  {
    "id": 13,
    "name": "Abcd Corp",
    "class": {
      "id": 0,
      "description": "Commercial"
    },
    "type": {
      "id": 2,
      "description": "Client"
    },
    "country": {
      "id": 74,
      "name": "Germany",
      "mcc": "262",
      "country_code": "49",
      "isocode": "de"
    },
    "status": {
      "id": 1,
      "description": "Suspended"
    },
    "relation": {
      "id": 18,
      "type": {
        "id": 0,
        "description": "Customer of"
      }
    },
    "monthly_cost_limit": 1000,
    "currency": {
      "id": 1,
      "code": "EUR",
      "symbol": "€"
    },
    "created": "2015-04-11T00:00:00.000+0000",
    "verification_type": {
      "id": 1,
      "description": "Business registration number"
    },
    "verification": "987654321"
  }
]
Create an Organisation
/api/v1/organisation?{q}{page}{per_page}{sort}

Creates the specified organisation.

ID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • Name (String required)

  • Class (Object required)

  • Type (Object required)

  • Country (Object required)

  • Status (Object optional)

  • Relation Type (Object required)

  • Currency (Object required)

  • Verification Type (Object optional)

  • Verification (String optional)

  • Monthly cost limit (Integer optional)

  • Ext reference (String optional)

Notes

  • If the status field is not set at creation time, the default imposed by server is ENABLED.
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "Tele17",
  "class": {
    "id": 0
  },
  "type": {
    "id": 1
  },
  "country": {
    "id": 12
  },
  "status": {
    "id": 0
  },
  "relation": {
    "type": {
      "id": 0
    }
  },
  "currency": {
    "id": 1
  },
  "verification_type": {
    "id": 1
  },
  "verification": "XYZ123",
  "ext_reference": "ref",
  "monthly_cost_limit": 1000
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/organisation/42

Organisation Operations 

Operations on a single organisation.

Retrieve a Single Organisation
/api/v1/organisation/{id}

You can retrieve details about your own organisation and your child organisations by id. The own organisation can also be retrieved with call to /api/v1/organisation/my

  • Parameters
  • id
    number (required) 

    Organisation ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 12,
  "name": "Tele17",
  "class": {
    "id": 0,
    "description": "Commercial"
  },
  "type": {
    "id": 1,
    "description": "Provider"
  },
  "country": {
    "id": 12,
    "name": "Germany"
  },
  "status": {
    "id": 0,
    "description": "Active"
  },
  "relation": {
    "id": 17,
    "type": {
      "id": 0,
      "description": "Customer of"
    }
  },
  "monthly_cost_limit": 1000,
  "currency": {
    "id": 1,
    "code": "EUR",
    "symbol": "€"
  },
  "created": "2015-04-11T00:00:00.000+0000",
  "verification_type": {
    "id": 1,
    "description": "Business registration number"
  },
  "verification": "987654321"
}
Update Organisation
/api/v1/organisation/{id}

You can update the following fields of your child organisations:

  • Name (String optional)

  • Class (Object optional)

  • Type (Object optional)

  • Country (Object optional)

  • Status (Object optional) - Status deleted cannot be set by PATCH.

  • Monthly cost limit (Integer optional)

  • Currency (Object optional)

  • Verification Type (Object optional)

  • Verification (String optional)

  • Ext reference (String optional)

  • Parameters
  • id
    number (required) 

    Organisation ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "Tele17",
  "class": {
    "id": 0
  },
  "type": {
    "id": 1
  },
  "country": {
    "id": 12
  },
  "status": {
    "id": 1
  },
  "ext_reference": "ref",
  "monthly_cost_limit": 2000,
  "currency": {
    "id": 2
  },
  "verification_type": {
    "id": 2
  },
  "verification": "ABC0987"
}
  • Response  204
Delete Organisation
/api/v1/organisation/{id}

Possibility to delete your child organisations.

Deletion of an organisation will also delete all his child organisations, his endpoints, SIMs and users.

  • Parameters
  • id
    number (required) 

    Organisation ID

  • Response  204

Retrieve Organisation Statuses 

Retrieve Organisation Statuses
/api/v1/organisation/status

Provides the list of available organisation status (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "description": "Enabled"
  },
  {
    "id": 1,
    "description": "Suspended"
  },
  {
    "id": 2,
    "description": "Deleted"
  }
]

Retrieve Available Organisation Types 

Retrieve Available Organisation Types
/api/v1/organisation/type

Provides the list of available organisation types (lookup), filtered according to which types can used to create a new organisation under the current user`s organisation.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "description": "Mobile Network Operator"
  },
  {
    "id": 2,
    "description": "Service Provider"
  },
  {
    "id": 3,
    "description": "Reseller"
  },
  {
    "id": 4,
    "description": "Enterprise"
  }
]

Retrieve Available Organisation Relation Types 

Retrieve Available Organisation Relation Types
/api/v1/organisation/relation/type

Provides the list of available organisation relation types (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "description": "Customer of"
  },
  {
    "id": 1,
    "description": "Resource Provider"
  },
  {
    "id": 2,
    "description": "Roaming Partner"
  }
]

Retrieve Available Organisation Verification Types 

Retrieve Available Organisation Verification Types
/api/v1/organisation/verification_type

Provides the list of available organisation verification types (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "description": "Business registration number"
  },
  {
    "id": 2,
    "description": "Passport"
  },
  {
    "id": 3,
    "description": "Identity card"
  },
  {
    "id": 4,
    "description": "VAT identification number"
  }
]

Contact Collection Management 

This group of services manages organisation contacts.

Below is the sample contact in JSON representation.

{
  "id": 1,
  "organisation": {
    "id": 124,
    "name": "Tele17 Austria"
  },
  "type": {
    "id": 1,
    "description": "Commercial"
  },
  "name": "Marc",
  "title": "Ing",
  "department": "Sales",
  "street": "1st street",
  "zipcode": "10224",
  "city": "Berlin",
  "country": {
    "id": 1,
    "name": "Germany"
  },
  "email": "user@domain.com",
  "phone": "+497 554 776 653",
  "mobile": "+497 554 776 653"
}

Description of contact properties

Here is the description of contact object

Name Type Description
id Integer Unique ID of this contact
organisation Object id (Integer) - ID of the organisation of this contact
name (String) - name of the organisation
type Object id (Integer) - ID of the type of this contact
description (String) - Description of meaning of the type
name String First and last name of the contact
title String Title of the contact
department String Department of the contact
street String Street and # of the contact
zipcode String ZIP of the contact
city String City of the contact
country Object id (Integer) - ID of the country of this organisation
name (String) - Country name
email String Email of the contact
phone String Phone number of the contact
mobile String Mobile number of the contact
Retrieve Contacts for an Organisation
/api/v1/organisation/{organisationId}/contact
  • Parameters
  • organisationId
    number (required) 

    Organisation ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "organisation": {
      "id": 124,
      "name": "Tele17 Austria"
    },
    "type": {
      "id": 1,
      "description": "Commercial"
    },
    "name": "Marc Muller",
    "title": "Ing",
    "department": "Sales",
    "street": "1st street",
    "zipcode": "10224",
    "city": "Berlin",
    "country": {
      "id": 1,
      "name": "Germany"
    },
    "email": "user@domain.com",
    "phone": "+497 554 776 653",
    "mobile": "+497 554 776 653"
  },
  {
    "id": 2,
    "organisation": {
      "id": 124,
      "name": "Tele17 Austria"
    },
    "type": {
      "id": 1,
      "description": "Finance"
    },
    "name": "Stefan Berg",
    "title": "Ing",
    "department": "Controlling",
    "street": "1st street",
    "zipcode": "10224",
    "city": "Berlin",
    "country": {
      "id": 1,
      "name": "Germany"
    },
    "email": "user@domain.com",
    "phone": "+497 554 776 654",
    "mobile": "+497 554 776 655"
  }
]
Create a Contact for an Organisation
/api/v1/organisation/{organisationId}/contact

Creates the specified contact.

ID and organisationID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • type (Object required)

  • name (String required)

  • title (String optional)

  • department (String optional)

  • street (String optional)

  • zipcode (String optional)

  • city (String optional)

  • country (Object required)

  • email (String required)

  • phone (String optional)

  • mobile (String optional)

  • Parameters
  • organisationId
    number (required) 

    Organisation ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "type": {
    "id": 1
  },
  "name": "Marc Muller",
  "title": "Ing",
  "department": "Sales",
  "street": "1st street",
  "zipcode": "10224",
  "city": "Berlin",
  "country": {
    "id": 1
  },
  "email": "user@domain.com",
  "phone": "+497 554 776 653",
  "mobile": "+497 554 776 653"
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/organisation/42/contact/11

Contact Management 

Retrieve a Single Contact
/api/v1/organisation/{organisationId}/contact/{contactId}
  • Parameters
  • organisationId
    number (required) 

    Organisation ID

    contactId
    number (required) 

    Contact ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 1,
  "organisation": {
    "id": 124,
    "name": "Tele17 Austria"
  },
  "type": {
    "id": 1,
    "description": "Commercial"
  },
  "name": "Marc",
  "title": "Ing",
  "department": "Sales",
  "street": "1st street",
  "zipcode": "10224",
  "city": "Berlin",
  "country": {
    "id": 1,
    "name": "Germany"
  },
  "email": "user@domain.com",
  "phone": "+497 554 776 653",
  "mobile": "+497 554 776 653"
}
Update a Single Contact
/api/v1/organisation/{organisationId}/contact/{contactId}
  • Parameters
  • organisationId
    number (required) 

    Organisation ID

    contactId
    number (required) 

    Contact ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "type": {
    "id": 1
  },
  "name": "Marc Muller",
  "title": "Ing",
  "department": "Sales",
  "street": "1st street",
  "zipcode": "10224",
  "city": "Berlin",
  "country": {
    "id": 1
  },
  "email": "user@domain.com",
  "phone": "+497 554 776 653",
  "mobile": "+497 554 776 653"
}
Delete a Single Contact
/api/v1/organisation/{organisationId}/contact/{contactId}
  • Parameters
  • organisationId
    number (required) 

    Organisation ID

    contactId
    number (required) 

    Contact ID

  • Response  204

Retrieve Available Contact Types 

Retrieve Available Contact Types
/api/v1/organisation/contact/type

Provides the list of available contact types (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "description": "Commercial"
  },
  {
    "id": 2,
    "description": "Technical"
  },
  {
    "id": 3,
    "description": "Finance"
  }
]

List of assigned tariffs 

Retrieve list of assigned tariffs for an organisation
/api/v1/organisation/{organisation_id}/tariff

Retrieve the list of assigned tariffs for my own organisation or for one of my child organisations

  • Parameters
  • organisation_id
    number (required) 

    Organisation ID - my own or a child organisation

  • Response  200
  • Body
    [
  {
    "id": 3,
    "name": "Tariff for M2M Europe",
    "description": "M2M Europe: Data+SMS",
    "created": "2015-01-10 09:36:58",
    "default_sms_mt_rate": 0.5,
    "default_sms_mo_rate": 0.4,
    "sim_issued_rate": 0.1,
    "sim_activated_rate": 0.2,
    "sim_suspended_rate": 0.3,
    "sim_activation_rate": 0.6,
    "sim_reactivation_rate": 0.8,
    "sim_suspension_rate": 0.7,
    "sim_termination_rate": 0.5,
    "status": {
      "description": "Active",
      "id": 1
    },
    "currency": {
      "id": 1,
      "code": "EUR",
      "symbol": "€"
    },
    "data_blocksize": {
      "id": 10,
      "octets": 1,
      "description": "exact"
    },
    "data_throttle": {
      "id": 9,
      "octets": 256000,
      "description": "256 kbit/s"
    },
    "pdp_context_definition": [
      {
        "id": 32,
        "apn": "internet.test.org",
        "default": true
      }
    ]
  }
]

Tariff in organisation 

Assign tariff to organisation
/api/v1/organisation/{organisation_id}/tariff/{tariff_id}

Assign a tariff to a child organisation.

  • Parameters
  • organisation_id
    number (required) 

    Organisation ID - must be a child organisation

    tariff_id
    number (required) 

    Tariff ID - must be a tariff of my organisation

  • Response  204
Remove tariff from organisation
/api/v1/organisation/{organisation_id}/tariff/{tariff_id}

Remove the assignment of a tariff from a child organisation.

  • Parameters
  • organisation_id
    number (required) 

    Organisation ID - must be a child organisation

    tariff_id
    number (required) 

    Tariff ID - must be a tariff of my organisation

  • Response  204

Events of an organisation 

Retrieve Events
/api/v1/organisation/{organisation_id}/event?{q}{page}{per_page}{sort}

Returns the list of events, filtered, sorted and paged according to query parameters.

The events of the own organisation can also be retrieved with call to /api/v1/organisation/my/event

  • Parameters
  • q
    number (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, i.e. timestamp, description, source, severity, organisation, endpoint, tags, ip_address, imei, iccid, imsi. Example q=source:2,tags:Monitoring

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields, i.e. timestamp, id.
    Example sort=-timestamp,id
    Sort by timestamp descending and id ascending

  • Response  200
  • Headers
    Link: <https://cdn.emnify.net/api/v1/organisation/2/event?q=source:2,tags:Monitoring&per_page=100&sort=-severity,timestamp>; rel="first", <https://cdn.emnify.net/api/v1/organisation/2/event?q=source:2,tags:Monitoring&page=5&per_page=100&sort=-severity,timestamp>; rel="prev", <https://cdn.emnify.net/api/v1/organisation/2/event?q=source:2,tags:Monitoring&page=7&per_page=100&sort=-severity,timestamp>; rel="next", <https://cdn.emnify.net/api/v1/organisation/2/event?q=source:2,tags:Monitoring&page=34&per_page=100&sort=-severity,timestamp>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: source:2,tags:Monitoring
    X-Sort: -severity,timestamp
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "timestamp": "2015-07-16 12:07:09",
    "alert": true,
    "description": "PDP Context deleted.",
    "id": 69535,
    "event_type": {
      "description": "Delete PDP Context",
      "id": 4
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 6
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 110
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    }
  }
]

SIMs 

This section describes available API services for managing the SIM resource. API provides services to retrieve the collection of SIMs with paging, filtering and sorting options. It also provides services for single SIM retrieval and CRUD operations via POST, PATCH and DELETE actions.

Below is the sample SIM in JSON representation. Apart from own data, the object contains embedded objects:

  • model

  • endpoint

{
  "id": 788,
  "iccid": "736826736473829773621",
  "production_date": "2014-08-01T08:47:00+0000",
  "activation_date": "2014-08-21T18:17:00+0000",
  "status": {
    "id": 1,
    "description": "Active"
  },
  "customer_org":{
    "id": 13,
    "name": "Enterprise",
    "country":{
      "id":205,
      "name":"United Kingdom"
    }
  },
  "issuer_org":{
    "id": 11,
    "name": "MNO",
    "country":{
      "id":205,
      "name":"United Kingdom"
    }
  },
  "endpoint": {
    "id": 1,
    "name": "arduino01",
    "imei": null,
    "imei_lock": false,
    "created": "2015-03-19T08:45:41.000+0000",
    "last_updated": "2015-03-19T08:45:41.000+0000",
    "organisation_id": 5,
    "service_profile_id": 1,
    "tariff_profile_id": 1,
    "tags": null,
    "ip_address": "10.1.1.9"
  },
  "imsi": "123451234567890",
  "msisdn": "+88563748761",
  "model": {
    "id": 1,
    "description": "Java smartcard",
    "memory_size": 64,
    "formfactor": {
      "id": 1,
      "name": "2FF",
      "image": "2ff.jpg"
    },
    "manufacturer": {
      "id": 1,
      "name": "Motorola"
    }
  }
}

Description of SIM Properties

Here is the description of SIM object:

Name Type Description
id Integer Unique ID of this SIM
iccid String integrated circuit card identifier
production_date Timestamp Timestamp when this SIM was created
- Type: ISO 8601 timestamp format
activation_date Timestamp Timestamp when this SIM was activated for the first time
- Type: ISO 8601 timestamp format
status Object id (Integer) - ID of status this SIM
description (String) - Description of meaning of the status
customer_org Object id (Integer) - ID of the organisation to whom the sim was issued
name (String) and country (Object) of that organisation
issuer_org Object id (Integer) - ID of the organisation who issued the sim
name (String) and country (Object) of that organisation
reseller_org Object id (Integer) - ID of the organisation who resold the sim
name (String) and country (Object) of that organisation
endpoint Object id (Integer) - ID of associated endpoint
name (String) - endpoint name
some more collapsed information of the endpoint -> Endpoint
imsi String IMSI number of the SIM
msisdn String MSISDN number of the SIM
model Object id (Integer) - ID of the SIM model
description (String) - Description of the model
memory_size (Integer) - Memory Size in KB
form factor (Object) - SIM form factor
manufacturer (Object) - manufacturer of the SIM

SIM Collection 

SIM collection service.

Retrieve SIM list
/api/v1/sim?{q}{page}{per_page}{sort}

Returns the list of SIMs, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    String (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, e.g. id, issuer_org, reseller_org, customer_org, iccid, status, production_date, imsi, msisdn, endpoint, model.
    Example q=model:1,issuer_org:11

    page
    Number (optional) 

    Paging parameters - current page

    per_page
    Number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields,
    id,
    issuer_org,
    reseller_org,
    customer_org,
    iccid,
    status,
    production_date,
    endpoint,
    model.

    Example sort=-status,id
    Sort by status descending and id ascending

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Link: <https://cdn.emnify.net/api/v1/sim?q=model:1,issuer_org:11&per_page=100&sort=-status,id>; rel="first", <https://cdn.emnify.net/api/v1/sim?q=model:1,issuer_org:11&page=5&per_page=100&sort=-status,id>; rel="prev", <https://cdn.emnify.net/api/v1/sim?q=model:1,issuer_org:11&page=7&per_page=100&sort=-status,id>; rel="next", <https://cdn.emnify.net/api/v1/sim?q=model:1,issuer_org:11&page=33&per_page=100&sort=-status,id>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: model:1,issuer_org:11
    X-Sort: -status,id
    X-Total-Count: 3325
    X-Total-Pages: 333
    Body
    [
  {
    "id": 788,
    "iccid": "736826736473829773621",
    "production_date": "2014-08-01T08:47:00+0000",
    "activation_date": "2014-08-21T18:17:00+0000",
    "status": {
      "id": 1,
      "description": "Active"
    },
    "customer_org": {
      "id": 13,
      "name": "Enterprise",
      "country": {
        "id": 205,
        "name": "United Kingdom"
      }
    },
    "issuer_org": {
      "id": 11,
      "name": "MNO",
      "country": {
        "id": 205,
        "name": "United Kingdom"
      }
    },
    "endpoint": {
      "id": 1,
      "name": "arduino01",
      "imei": null,
      "imei_lock": false,
      "created": "2015-03-19T08:45:41.000+0000",
      "last_updated": "2015-03-19T08:45:41.000+0000",
      "organisation_id": 13,
      "service_profile_id": 1,
      "tariff_profile_id": 1,
      "tags": null,
      "ip_address": "10.1.1.9"
    },
    "imsi": "123451234567890",
    "msisdn": "+88563748761",
    "model": {
      "id": 1,
      "description": "Java smartcard",
      "memory_size": 64,
      "formfactor": {
        "id": 1,
        "name": "2FF",
        "image": "2ff.jpg"
      },
      "manufacturer": {
        "id": 1,
        "name": "Motorola"
      }
    }
  },
  {
    "id": 789,
    "iccid": "736826736473229773622",
    "production_date": "2014-08-01T08:48:00+0000",
    "status": {
      "id": 0,
      "description": "Issued"
    },
    "customer_org": {
      "id": 42,
      "name": "another Enterprise",
      "country": {
        "id": 74,
        "name": "Germany"
      }
    },
    "issuer_org": {
      "id": 11,
      "name": "MNO",
      "country": {
        "id": 205,
        "name": "United Kingdom"
      }
    },
    "reseller_org": {
      "id": 22,
      "name": "Reseller",
      "country": {
        "id": 205,
        "name": "United Kingdom"
      }
    },
    "endpoint": {
      "id": 23,
      "name": "arduino02",
      "imei": null,
      "imei_lock": false,
      "created": "2015-03-29T08:45:41.000+0000",
      "last_updated": "2015-04-19T08:45:41.000+0000",
      "organisation_id": 42,
      "service_profile_id": 1,
      "tariff_profile_id": 1,
      "tags": null,
      "ip_address": "10.1.2.2"
    },
    "imsi": "123451234567811",
    "msisdn": "+88563748762",
    "model": {
      "id": 1,
      "description": "Java smartcard",
      "memory_size": 64,
      "formfactor": {
        "id": 1,
        "name": "2FF",
        "image": "2ff.jpg"
      },
      "manufacturer": {
        "id": 1,
        "name": "Motorola"
      }
    }
  }
]

SIM 

Create the specified SIM. (not implemented yet)

Create SIM
/api/v1/sim

Create the specified SIM

ID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • Produced (Date optional)

  • Status (Object required)

  • ICCID (String required)

  • Model (Object optional)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "produced": "2014-08-01T08:47:00+00:00",
  "status": {
    "id": 3
  },
  "iccid": "736826736473829773623",
  "model": {
    "id": 2
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/sim/42

SIM Operations 

SIM operations.

Retrieve SIM By ID
/api/v1/sim/{id}

Retrieve SIM details for a given ID.

  • Parameters
  • id
    number (required) 

    SIM ID

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    Body
    {
  "id": 788,
  "iccid": "736826736473229773621",
  "production_date": "2014-08-01T08:48:00+0000",
  "activation_date": "2014-08-21T18:17:00+0000",
  "status": {
    "id": 1,
    "description": "Active"
  },
  "customer_org": {
    "id": 42,
    "name": "another Enterprise",
    "country": {
      "id": 74,
      "name": "Germany"
    }
  },
  "issuer_org": {
    "id": 11,
    "name": "MNO",
    "country": {
      "id": 205,
      "name": "United Kingdom"
    }
  },
  "reseller_org": {
    "id": 22,
    "name": "Reseller",
    "country": {
      "id": 205,
      "name": "United Kingdom"
    }
  },
  "endpoint": {
    "id": 23,
    "name": "arduino02",
    "imei": null,
    "imei_lock": false,
    "created": "2015-03-29T08:45:41.000+0000",
    "last_updated": "2015-04-19T08:45:41.000+0000",
    "organisation_id": 42,
    "service_profile_id": 1,
    "tariff_profile_id": 1,
    "tags": null,
    "ip_address": "10.1.2.2"
  },
  "imsi": "123451234567811",
  "msisdn": "+88563748762",
  "model": {
    "id": 1,
    "description": "Java smartcard",
    "memory_size": 64,
    "formfactor": {
      "id": 1,
      "name": "2FF",
      "image": "2ff.jpg"
    },
    "manufacturer": {
      "id": 1,
      "name": "Motorola"
    }
  }
}
Delete SIM
/api/v1/sim/{id}

Deletes SIM. SIMs with an endpoint assigned cannot be deleted.

  • Parameters
  • id
    number (required) 

    SIM ID

  • Response  204
Update SIM
/api/v1/sim/{id}

Update SIM resource.

You can provide the following fields with this request:

  • Issuer Organisation (Object optional) - can be changed to a direct child organisation of appropriate type

  • Reseller Organisation (Object optional) - can be changed to a direct child organisation of appropriate type or emptied ("reseller_org":{"id": null} or "reseller_org":{})

  • Customer Organisation (Object optional) - can be changed to own organisation or a direct child organisation of type “Enterprise” or emptied ("customer_org":{"id": null} or "customer_org":{})

  • Status (Object optional)

Notes on update restrictions:

  • A user of the Issuer organisation can update any of the updateable fields

  • A user of the Reseller organisation can update the fields: reseller_org, customer_org

  • A user of the Customer organisation can only update the status field

  • The issuer_org can be updated to a child organisation of type “Mobile Network Operator” or “Service Provider”

  • The reseller_org can be updated to a child organisation of type “Mobile Network Operator” or “Service Provider” or “Reseller”

  • The customer_org can be updated to a child organisation of type “Enterprise”

  • The status can be updated from id 0 (“Issued”) only to id 1 (“Activated”)

  • The status can also be updated between id 1 (“Activated”) and id 2 (“Suspended”) back and forth

  • Parameters
  • id
    number (required) 

    SIM ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "issuer_org": {
    "id": 3
  },
  "reseller_org": {
    "id": 5
  },
  "customer_org": {
    "id": 12
  },
  "status": {
    "id": 2
  }
}
  • Response  204
  • Response  400
  • Body
    {
  "error_code": 1406,
  "error_token": "NotAllowed",
  "message": "Patching the reseller organisation of the SIM to an Enterprise not allowed."
}

SIM Status 

List of All Available SIM Statuses
/api/v1/sim/status

  • The initial state after the SIM has been registered to an account is ‘Issued’.

  • Once you activate it the SIM becames ‘Active’.

  • When you suspend the SIM its status is set to ‘Suspended’.

  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Issued"
  },
  {
    "id": 1,
    "description": "Activated"
  },
  {
    "id": 2,
    "description": "Suspended"
  },
  {
    "id": 3,
    "description": "Deleted"
  }
]

Events of a SIM 

Retrieve Events
/api/v1/sim/{sim_id}/event?{q}{page}{per_page}{sort}

Returns the list of events, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    number (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, i.e. timestamp, description, source, severity, organisation, endpoint, tags, ip_address, imei, iccid, imsi. Example q=source:2,tags:Monitoring

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields, i.e. timestamp, id.
    Example sort=-timestamp,id
    Sort by timestamp descending and id ascending

  • Response  200
  • Headers
    Link: <https://cdn.emnify.net/api/v1/sim/2/event?q=source:2,tags:Monitoring&per_page=100&sort=-severity,timestamp>; rel="first", <https://cdn.emnify.net/api/v1/sim/2/event?q=source:2,tags:Monitoring&page=5&per_page=100&sort=-severity,timestamp>; rel="prev", <https://cdn.emnify.net/api/v1/sim/2/event?q=source:2,tags:Monitoring&page=7&per_page=100&sort=-severity,timestamp>; rel="next", <https://cdn.emnify.net/api/v1/sim/2/event?q=source:2,tags:Monitoring&page=34&per_page=100&sort=-severity,timestamp>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: source:2,tags:Monitoring
    X-Sort: -severity,timestamp
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "timestamp": "2015-07-16 12:07:09",
    "alert": true,
    "description": "PDP Context deleted.",
    "id": 69535,
    "event_type": {
      "description": "Delete PDP Context",
      "id": 4
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 6
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 2
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    }
  }
]

IMSIs 

This section describes available API services for managing the IMSI resource. The API provides services to retrieve the collection of IMSIs or a single IMSI, as well as CRUD operations via POST, PATCH and DELETE actions.

Below is the sample IMSI in JSON representation. Apart from own data, the object contains embedded objects:

  • IMSI pool

  • SIM

{
  "id": 17,
  "imsi": "112201234567008",
  "import_date": "2015-03-25T13:12:39.000+0000",
  "status": {
    "id": 0,
    "description": "Enabled"
  },
  "imsi_pool": {
    "id": 7,
    "description": "MNO 1 Pool",
    "network_coverage_id": 2,
    "resource_provider": {
      "id": 3,
      "status_id": 0,
      "organisation_id": 4,
      "organisation_name": "MNO 1"
    }
  },
  "type": {
     "id": 0,
     "description": "Root IMSI"
  },
  "sim": {
    "id": 20,
    "iccid": "6660000000000000005",
    "production_date": null,
    "status_id": 0,
    "sim_model_id": 3,
    "customer_org": {
      "id": 11,
      "name": "Reseller 3 C5",
      "type_id": 3,
      "country_id": 14,
      "status_id": 0,
      "ext_reference": null
    },
    "issuer_org": {
      "id": 5,
      "name": "Service Provider 1",
      "type_id": 2,
      "country_id": 205,
      "status_id": 0,
      "ext_reference": null
    }
  }
}

Description of IMSI Properties

Here is the description of the IMSI object:

Name Type Description
id Integer Unique ID of this IMSI
imsi String IMSI number of the SIM
import_date Timestamp Timestamp when this IMSI was imported into the system
- Type: ISO 8601 timestamp format
status Object id (Integer) - ID of status for this IMSI
description (String) - Description for this status
imsi_pool Object id (Integer) - ID of the pool to which the IMSI belongs
description (String) of the pool
network_coverage_id (Integer)
resource_provider (Object)
type Object id (Integer) - ID type for this IMSI
description (String) for this type
sim Object id (Integer) - ID of the SIM
etc. (refer to the SIMs section for a complete description of SIM fields)

IMSI Collection 

List of IMSIs
/api/v1/imsi?{q}{page}{per_page}{sort}

Returns the list of IMSIs, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    String (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, i.e. id, status, imsi, sim, import_date, type, imsi_pool.
    Example q=status:0,imsi_pool:7

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields,
    id,
    status,
    imsi,
    sim,
    import_date,
    type,
    imsi_pool.

    Example sort=-status,id
    Sort by status descending and id ascending

  • Response  200
  • Headers
    Content-Type: application/json
    Link: <https://cdn.emnify.net/api/v1/imsi?q=status:0,imsi_pool:7&per_page=10&sort=-status,id>; rel="first", <https://cdn.emnify.net/api/v1/imsi?q=status:0,imsi_pool:7&page=5&per_page=10&sort=-status,id>; rel="prev", <https://cdn.emnify.net/api/v1/imsi?q=status:0,imsi_pool:7&page=7&per_page=10&sort=-status,id>; rel="next", <https://cdn.emnify.net/api/v1/imsi?q=status:0,imsi_pool:7&page=34&per_page=10&sort=-status,id>; rel="last"
    X-Count-Per-Page: 10
    X-Current-Page: 6
    X-Filter: status:0,imsi_pool:7
    X-Sort: -status,id
    X-Total-Count: 335
    X-Total-Pages: 34
    Body
    [
  {
    "id": 17,
    "imsi": "112201234567008",
    "import_date": "2015-03-25T13:12:39.000+0000",
    "status": {
      "id": 0,
      "description": "Enabled"
    },
    "imsi_pool": {
      "id": 7,
      "description": "MNO 1 Pool",
      "network_coverage_id": 2,
      "resource_provider": {
        "id": 3,
        "status_id": 0,
        "organisation_id": 4,
        "organisation_name": "MNO 1"
      }
    },
    "type": {
      "id": 0,
      "description": "Root IMSI"
    },
    "sim": {
      "id": 20,
      "iccid": "6660000000000000005",
      "production_date": null,
      "status_id": 0,
      "sim_model_id": 3,
      "customer_org": {
        "id": 11,
        "name": "Reseller 3 C5",
        "type_id": 3,
        "country_id": 14,
        "status_id": 0,
        "ext_reference": null
      },
      "issuer_org": {
        "id": 5,
        "name": "Service Provider 1",
        "type_id": 2,
        "country_id": 205,
        "status_id": 0,
        "ext_reference": null
      }
    }
  },
  {
    "id": 18,
    "imsi": "232201234567456",
    "import_date": "2015-03-27T17:16:32.000+0000",
    "status": {
      "id": 0,
      "description": "Enabled"
    },
    "imsi_pool": {
      "id": 7,
      "description": "MNO 1 Pool",
      "network_coverage_id": 2,
      "resource_provider": {
        "id": 3,
        "status_id": 0,
        "organisation_id": 4,
        "organisation_name": "MNO 1"
      }
    },
    "type": {
      "id": 0,
      "description": "Root IMSI"
    },
    "sim": {
      "id": 21,
      "iccid": "6660000000000000006",
      "production_date": null,
      "status_id": 0,
      "sim_model_id": 3,
      "customer_org": {
        "id": 11,
        "name": "Reseller 3 C5",
        "type_id": 3,
        "country_id": 14,
        "status_id": 0,
        "ext_reference": null
      },
      "issuer_org": {
        "id": 5,
        "name": "Service Provider 1",
        "type_id": 2,
        "country_id": 205,
        "status_id": 0,
        "ext_reference": null
      }
    }
  }
]

Retrieve IMSI By ID 

Retrieve IMSI By ID
/api/v1/imsi/{id}

Retrieve IMSI details for a given ID.

  • Parameters
  • id
    number (required) 

    IMSI ID

  • Response  200
  • Body
    {
  "id": 17,
  "imsi": "112201234567008",
  "import_date": "2015-03-25T13:12:39.000+0000",
  "status": {
    "id": 0,
    "description": "Enabled"
  },
  "imsi_pool": {
    "id": 7,
    "description": "MNO 1 Pool",
    "network_coverage_id": 2,
    "resource_provider": {
      "id": 3,
      "status_id": 0,
      "organisation_id": 4,
      "organisation_name": "MNO 1"
    }
  },
  "type": {
    "id": 0,
    "description": "Root IMSI"
  },
  "sim": {
    "id": 20,
    "iccid": "6660000000000000005",
    "production_date": null,
    "status_id": 0,
    "sim_model_id": 3,
    "customer_org": {
      "id": 11,
      "name": "Reseller 3 C5",
      "type_id": 3,
      "country_id": 14,
      "status_id": 0,
      "ext_reference": null
    },
    "issuer_org": {
      "id": 5,
      "name": "Service Provider 1",
      "type_id": 2,
      "country_id": 205,
      "status_id": 0,
      "ext_reference": null
    }
  }
}
Update IMSI
/api/v1/imsi/{id}

You can enable/disable an IMSI by updating its status, provided that it is assigned to one of your SIM cards or your organisation is the IMSI resource provider:

  • status (Object, optional)
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "status": {
    "id": 1
  }
}
  • Response  204

Imsi Status 

List of all available IMSI statuses
/api/v1/imsi/status
  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Enabled"
  },
  {
    "id": 1,
    "description": "Disabled"
  }
]

Events of an IMSI 

Retrieve Events
/api/v1/imsi/{imsi_id}/event?{q}{page}{per_page}{sort}

Returns the list of events, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    number (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, e.g. timestamp, description, source, severity, organisation, endpoint, tags, ip_address, imei, iccid, imsi. Example q=source:2,tags:Monitoring

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields, e.g. timestamp, id.
    Example sort=-timestamp,id
    Sort by timestamp descending and id ascending

  • Response  200
  • Headers
    Link: <https://cdn.emnify.net/api/v1/imsi/2/event?q=source:2,tags:Monitoring&per_page=100&sort=-severity,timestamp>; rel="first", <https://cdn.emnify.net/api/v1/imsi/2/event?q=source:2,tags:Monitoring&page=5&per_page=100&sort=-severity,timestamp>; rel="prev", <https://cdn.emnify.net/api/v1/imsi/2/event?q=source:2,tags:Monitoring&page=7&per_page=100&sort=-severity,timestamp>; rel="next", <https://cdn.emnify.net/api/v1/imsi/2/event?q=source:2,tags:Monitoring&page=34&per_page=100&sort=-severity,timestamp>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: source:2,tags:Monitoring
    X-Sort: -severity,timestamp
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "timestamp": "2015-07-16 12:07:09",
    "alert": true,
    "description": "PDP Context deleted.",
    "id": 69535,
    "event_type": {
      "description": "Delete PDP Context",
      "id": 4
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 6
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 2
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    }
  }
]

Tariffs 

This section describes available API services for managing tariff resources. The API provides services to retrieve the collection of tariffs or a single tariff, as well as CRUD operations via POST, GET, PATCH and DELETE actions.

The API entry points for tariffs cannot be used by ‘Enterprise’ Organisations. Rates can only be positive decimal numbers (negative values are not allowed)

Below is a sample tariff in JSON representation.

{
  "id": 3,
  "name": "Tariff for M2M Europe",
  "description": "M2M Europe: Data+SMS",
  "created": "2015-01-10 09:36:58",
  "default_sms_mt_rate": 0.5,
  "default_sms_mo_rate": 0.4,
  "sim_issued_rate": 0.1,
  "sim_activated_rate": 0.2,
  "sim_suspended_rate": 0.3,
  "sim_activation_rate": 0.6,
  "sim_reactivation_rate": 0.8,
  "sim_suspension_rate": 0.7,
  "sim_termination_rate": 0.5,
  "used_count": 2,
  "assigned_count": 1,
  "status": {
    "description": "Active",
    "id": 1
  },
  "currency": {
    "id": 1,
    "code": "EUR",
    "symbol": "€"
  },
  "data_blocksize": {
    "id": 10,
    "octets": 1,
    "description": "exact"
  },
  "data_throttle": {
    "id": 9,
    "octets": 256000,
    "description": "256 kbit/s"
  },
  "pdp_context_definition": [
    {
      "id": 32,
      "apn": "internet.test.org",
      "default": true
    }
  ]
}

Description of Tariff Properties

Here is the description of the tariff object:

Name Type Description
id Integer Unique ID of this tariff
name String short name of this tariff
description String long description of this tariff
created Timestamp Timestamp when this tariff was created
- Type: ISO 8601 timestamp format
default_sms_mt_rate Double default rate for SMS Mobile Terminated
default_sms_mo_rate Double default rate for SMS Mobile Originated
sim_issued_rate Double rate for issued SIM
sim_activated_rate Double rate for activated SIM
sim_suspended_rate Double rate for suspended SIM
sim_activation_rate Double SIM activation rate
sim_reactivation_rate Double SIM reactivation rate
sim_suspension_rate Double SIM suspension rate
sim_termination_rate Double SIM termination rate
used_count Integer count of entries in tariff_profile table referencing this tariff
assigned_count Integer count of entries in organisation_tariff_assignment table referencing this tariff
status Object id (Integer) - ID of status for this tariff
description (String) - Description for this status
currency Object id (Integer) - ID currency for this tariff
code (String) for this currency
symbol (String) for this currency
data_blocksize Object id (Integer) - ID data block size for this tariff
octets (Integer) for this data block size
description (String) for this data blocksize
data_throttle Object id (Integer) - ID data throttle for this tariff
octets (Integer) for this data throttle
description (String) for this data throttle
pdp_context_definition Object list of PDP context definitions assigned to this tariff

Tariff Collection 

List of Tariffs
/api/v1/tariff

Returns the list of tariffs of the user`s own organisation.

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    X-Total-Count: 2
    Body
    [
  {
    "id": 3,
    "name": "Tariff for M2M Europe",
    "description": "M2M Europe: Data+SMS",
    "created": "2015-01-10 09:36:58",
    "default_sms_mt_rate": 0.5,
    "default_sms_mo_rate": 0.4,
    "sim_issued_rate": 0.1,
    "sim_activated_rate": 0.2,
    "sim_suspended_rate": 0.3,
    "sim_activation_rate": 0.6,
    "sim_reactivation_rate": 0.8,
    "sim_suspension_rate": 0.7,
    "sim_termination_rate": 0.5,
    "used_count": 2,
    "assigned_count": 1,
    "status": {
      "description": "Active",
      "id": 1
    },
    "currency": {
      "code": "EUR",
      "symbol": "€",
      "id": 1
    },
    "data_blocksize": {
      "id": 10,
      "octets": 1,
      "description": "exact"
    },
    "data_throttle": {
      "id": 9,
      "octets": 256000,
      "description": "256 kbit/s"
    },
    "pdp_context_definition": [
      {
        "id": 32,
        "apn": "internet.test.org",
        "default": true
      }
    ]
  },
  {
    "id": 2,
    "name": "Tariff 2",
    "description": null,
    "created": "2015-01-10 09:51:30",
    "default_sms_mt_rate": 0.1,
    "default_sms_mo_rate": 0.1,
    "sim_issued_rate": 0,
    "sim_activated_rate": 0,
    "sim_suspended_rate": 0,
    "sim_activation_rate": 0,
    "sim_reactivation_rate": 0,
    "sim_suspension_rate": 0,
    "sim_termination_rate": 0,
    "used_count": 0,
    "assigned_count": 0,
    "status": {
      "description": "Active",
      "id": 1
    },
    "currency": {
      "code": "EUR",
      "symbol": "€",
      "id": 1
    },
    "data_blocksize": null,
    "data_throttle": null,
    "pdp_context_definition": [
      {
        "id": 22,
        "apn": "internet.test.com",
        "default": false
      }
    ]
  }
]
Create Tariff
/api/v1/tariff

Create the specified tariff

ID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • name (String required)

  • description (String optional)

  • default_sms_mt_rate (Double optional, Default=0.0)

  • default_sms_mo_rate (Double optional, Default=0.0)

  • sim_activated_rate (Double optional, Default=0.0)

  • sim_suspended_rate (Double optional, Default=0.0)

  • sim_activation_rate (Double optional, Default=0.0)

  • sim_reactivation_rate (Double optional, Default=0.0)

  • sim_suspension_rate (Double optional, Default=0.0)

  • sim_termination_rate (Double optional, Default=0.0)

  • currency (Object optional, Default={“id”:1})

  • data_blocksize (Object optional)

  • data_throttle (Object optional)

The Status for a new tariff is always ‘STAGING’!

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "new name",
  "description": "new description",
  "default_sms_mt_rate": 11.1,
  "default_sms_mo_rate": 22.2,
  "sim_issued_rate": 33.3,
  "sim_activated_rate": 44.4,
  "sim_suspended_rate": 55.5,
  "sim_activation_rate": 66.6,
  "sim_reactivation_rate": 77.7,
  "sim_suspension_rate": 88.8,
  "sim_termination_rate": 99.9,
  "currency": {
    "id": 2
  },
  "data_blocksize": {
    "id": 1
  },
  "data_throttle": {
    "id": 2
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/tariff/42

Single Tariff Operations 

Retrieve Tariff
/api/v1/tariff/{id}

Returns tariff specified by id.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 3,
  "name": "Tariff for M2M Europe",
  "description": "M2M Europe: Data+SMS",
  "created": "2015-01-10 09:36:58",
  "default_sms_mt_rate": 0.5,
  "default_sms_mo_rate": 0.4,
  "sim_issued_rate": 0.1,
  "sim_activated_rate": 0.2,
  "sim_suspended_rate": 0.3,
  "sim_activation_rate": 0.6,
  "sim_reactivation_rate": 0.8,
  "sim_suspension_rate": 0.7,
  "sim_termination_rate": 0.5,
  "used_count": 2,
  "assigned_count": 1,
  "status": {
    "description": "Active",
    "id": 1
  },
  "currency": {
    "code": "EUR",
    "symbol": "€",
    "id": 1
  },
  "data_blocksize": {
    "id": 10,
    "octets": 1,
    "description": "exact"
  },
  "data_throttle": {
    "id": 9,
    "octets": 256000,
    "description": "256 kbit/s"
  },
  "pdp_context_definition": [
    {
      "id": 32,
      "apn": "internet.test.org",
      "default": true
    }
  ]
}
Patch Tariff
/api/v1/tariff/{id}

Patch the specified tariff

You can provide following fields with this request:

  • name (String optional)

  • description (String optional)

  • default_sms_mt_rate (Double optional)

  • default_sms_mo_rate (Double optional)

  • sim_activated_rate (Double optional)

  • sim_suspended_rate (Double optional)

  • sim_activation_rate (Double optional)

  • sim_reactivation_rate (Double optional)

  • sim_suspension_rate (Double optional)

  • sim_termination_rate (Double optional)

  • status (Object optional)

  • currency (Object optional)

  • data_blocksize (Object optional)

  • data_throttle (Object optional)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "updated name",
  "description": "updated description",
  "default_sms_mt_rate": 11.1,
  "default_sms_mo_rate": 22.2,
  "sim_issued_rate": 33.3,
  "sim_activated_rate": 44.4,
  "sim_suspended_rate": 55.5,
  "sim_activation_rate": 66.6,
  "sim_reactivation_rate": 77.7,
  "sim_suspension_rate": 88.8,
  "sim_termination_rate": 99.9,
  "status": {
    "id": 1
  },
  "currency": {
    "id": 1
  },
  "data_blocksize": {
    "id": 1
  },
  "data_throttle": {
    "id": 2
  }
}
  • Response  204
Delete Tariff
/api/v1/tariff/{id}

Deletes tariff. Tariffs used by a tariff profile (used_count>0) or assigned to any organisation (assigned_count>0) cannot be deleted.

  • Parameters
  • id
    number (required) 

    tariff ID

  • Response  204

Tariff Status 

List of available Tariff statuses
/api/v1/tariff/status

Retrieve a list of the possible tariff statuses

  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Staging"
  },
  {
    "id": 1,
    "description": "Active"
  }
]

Ratezone Operations 

List of Ratezones
/api/v1/tariff/{id}/ratezone

Returns the list of ratezones for a tariff of the user`s own organisation.

  • Parameters
  • id
    number (required) 

    tariff ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 4,
    "name": "Zone 1",
    "status": {
      "id": 0,
      "description": "Staging"
    },
    "valid_from": "2015-06-06 00:00:00",
    "valid_until": null,
    "coverage": [
      {
        "id": 2,
        "name": "Telekom",
        "country": {
          "name": "Germany",
          "country_code": "49",
          "mcc": "262",
          "iso_code": "",
          "id": 74
        }
      },
      {
        "id": 3,
        "name": "Vodafone",
        "country": {
          "id": 74,
          "name": "Germany",
          "country_code": "49",
          "mcc": "262",
          "iso_code": ""
        }
      }
    ],
    "rate": [
      {
        "id": 5,
        "rate": 0.5,
        "volume": 1,
        "valid_from": "2016-05-05 00:00:00",
        "valid_until": null,
        "currency": {
          "id": 1,
          "code": "EUR",
          "symbol": "€"
        },
        "service": {
          "id": 38,
          "description": "All Data Services",
          "teleservice_code": 112,
          "used_with_vlr": true,
          "used_with_sgsn": true,
          "traffic_type": {
            "id": 5,
            "description": "Data",
            "unit": "MB"
          }
        }
      }
    ]
  }
]
Add Ratezone to Tariff
/api/v1/tariff/{id}/ratezone

Create the specified ratezone for a tariff

ID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • name (String required, unique for tariff!)

  • valid_from (Date (ISO 8601) optional, Default=Date and Time of creation)

  • valid_until (Date (ISO 8601) optional)

  • valid_until must be after valid_from!
  • The Status for a new ratezone is always ‘STAGING’!
  • The Name of a ratezone must be unique for the tariff it`s created for!
  • Parameters
  • id
    number (required) 

    tariff ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "new name",
  "valid_from": "2016-02-03T20:00:00+00:00",
  "valid_until": "2017-02-03T00:00:00+00:00"
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/tariff/42/ratezone/66

Single Ratezone Operations 

Patch Ratezone
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}

Following fields of the rate zone can be patched:

  • name (String, optional) the same name may not be used twice in a tariff

  • status (Object, optional)

  • valid_from (Date in ISO 8601, optional)

  • valid_until (Date in ISO 8601 or null, optional) Setting valid_until to null means valid forever

On changing the validity time frame all the rate of that rate zone must be inside the newly defined time frame.

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "updated name",
  "status": {
    "id": 1
  },
  "valid_from": "2012-02-01T00:00:00+0200",
  "valid_until": null
}
  • Response  204
Delete Ratezone from Tariff
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}

Deletes the specified ratezone from a tariff.

A ratezone can only be deleted after all its Rates have already been deleted!

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

  • Response  204
  • Response  409
  • Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Ratezone still referenced by Rate."
}

Ratezone Status 

List of available ratezone statuses
/api/v1/ratezone/status

Retrieve a list of the possible ratezone statuses

  • Response  200
  • Body
    [
  {
    "id": 0,
    "description": "Staging"
  },
  {
    "id": 1,
    "description": "Active"
  }
]

Operator Coverage of Ratezone 

Add Operator to Coverage of Ratezone
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}/coverage/{operator_id}

Assign the specified Operator to the coverage of the given ratezone of a tariff

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

    operator_id
    number (required) 

    operator ID

  • Response  204
  • Response  409
  • Body
    {
  "error_code": 2600,
  "error_token": "AlreadyAssigned",
  "message": "Operator 2 already assigned to ratezone 1"
}
Delete Operator from Coverage of Ratezone
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}/coverage/{operator_id}

Delete the specified Operator from the coverage of the given ratezone of a tariff

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

    operator_id
    number (required) 

    operator ID

  • Response  204

Add Rate to a Ratezone 

Add Rate to a Ratezone
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}/rate

Define a rate for a ratezone. You cannot have multiple rates for a certain service with overlapping time frame in the same ratezone.

You can provide following fields with the request:

  • rate (Double, required)

  • volume (Double, required)

  • currency (Object, required) - only id to specify

  • service (Object, required) - only id to specify

  • valid_from (Date (ISO 8601) optional, Default=Date and Time of creation)

  • valid_until (Date (ISO 8601) optional)

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

  • Request
  • Body
    {
  "rate": 1,
  "volume": 20,
  "currency": {
    "id": 1
  },
  "service": {
    "id": 6
  },
  "valid_from": "2015-08-01T00:00:00+0200",
  "valid_until": "2017-07-31T23:59:59+0200"
}
  • Response  201

Rate in a Ratezone 

Update Rate of a Ratezone
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}/rate/{rate_id}

Update a Rate of a ratezone. Only the valid time period can be updated. You cannot have multiple rates for a certain service with overlapping time frame in the same ratezone.

You can only provide the date fields with the request:

  • valid_from (Date (ISO 8601) optional, Default=Date and Time of creation)

  • valid_until (Date (ISO 8601) optional) - if set to null, the expiration date will be removed for this rate and it will valid indefinitely.

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

    rate_id
    number (required) 

    rate ID

  • Request
  • Body
    {
  "valid_from": "2015-08-01T00:00:00+0200",
  "valid_until": null
}
  • Response  204
Delete Rate of a Ratezone
/api/v1/tariff/{tariff_id}/ratezone/{ratezone_id}/rate/{rate_id}

Deletes a Rate of a ratezone.

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    ratezone_id
    number (required) 

    ratezone ID

    rate_id
    number (required) 

    rate ID

  • Response  204

PDP Context Definition 

Assign a PDP Context Definition to a Tariff
/api/v1/tariff/{tariff_id}/pdp_context_definition/{id}

Assign one of the PDP Context Definitions of your organisation to a tariff. There is a maximum of 3 PDP Context Definitions that can be assigned per tariff.

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    id
    number (required) 

    PDP context definition ID

  • Response  204
  • Response  400
  • Body
    {
  "error_code": 1406,
  "error_token": "NotAllowed",
  "message": "Assigning more than 3 pdp_context_definition to a tariff not allowed."
}
Remove a PDP Context Definition from a Tariff
/api/v1/tariff/{tariff_id}/pdp_context_definition/{id}

Remove one of the assigned PDP Context Definitions from a tariff.

  • Parameters
  • tariff_id
    number (required) 

    tariff ID

    id
    number (required) 

    PDP context definition ID

  • Response  204

Tariff Profiles 

This section describes available API services for managing tariff profile resources. The API provides services to retrieve the collection of tariff profiles or a single tariff profile, as well as CRUD operations via POST, GET, PATCH and DELETE actions.

Below is a sample tariff profile in JSON representation.

{
  "id": 1,
  "name": "Tariff Profile 1",
  "description": "This Tariff Profile is for testing.",
  "used_count": 56,
  "tariff": {
    "id": 1,
    "name": "Tariff 1",
    "description": "Tariff only for testing.",
    "created": "2014-10-20 00:00:00",
    "default_sms_mt_rate": 0.06,
    "default_sms_mo_rate": 0.06,
    "sim_issued_rate": 0,
    "sim_activated_rate": 1,
    "sim_suspended_rate": 0,
    "sim_activation_rate": 0,
    "sim_reactivation_rate": 0.5,
    "sim_suspension_rate": 0.5,
    "sim_termination_rate": 0,
    "currency": {
      "id": 1,
      "code": "EUR",
      "symbol": "€"
    },
    "data_blocksize": {
      "id": 1,
      "description": "exact",
      "octets": 1
    },
    "data_throttle": {
      "id": 1,
      "description": "256 kbit/s",
      "octets": 256000
    },
    "pdp_context_definition": [
      {
        "id": 12,
        "apn": "internet.test.com",
        "default": true
      }
    ]
  }
}

Description of Tariff Profile Properties

Here is the description of the tariff profile object:

Name Type Description
id Integer Unique ID of this tariff profile
name String short name of this tariff profile
description String long description of this tariff profile
used_count Integer number of Endpoints which have this tariff profile assigned
tariff Object tariff which this profile belongs to

Tariff Profile Collection 

List of Tariff Profiles
/api/v1/tariff_profile

Returns the list of tariff profiles of the user`s own organisation.

  • Response  200

  • Model description

    Headers
    Content-Type: application/json
    X-Total-Count: 2
    Body
    [
  {
    "id": 1,
    "name": "Tariff Profile 1",
    "description": "This Tariff Profile is for testing.",
    "used_count": 56,
    "tariff": {
      "id": 1,
      "name": "Tariff 1",
      "description": "Tariff only for testing.",
      "created": "2014-10-20 00:00:00",
      "default_sms_mt_rate": 0.06,
      "default_sms_mo_rate": 0.06,
      "sim_issued_rate": 0,
      "sim_activated_rate": 1,
      "sim_suspended_rate": 0,
      "sim_activation_rate": 0,
      "sim_reactivation_rate": 0.5,
      "sim_suspension_rate": 0.5,
      "sim_termination_rate": 0,
      "currency": {
        "id": 1,
        "code": "EUR",
        "symbol": "€"
      },
      "data_blocksize": {
        "id": 1,
        "description": "exact",
        "octets": 1
      },
      "data_throttle": {
        "id": 1,
        "description": "256 kbit/s",
        "octets": 256000
      },
      "pdp_context_definition": [
        {
          "id": 12,
          "apn": "internet.test.com",
          "default": true
        }
      ]
    }
  },
  {
    "id": 2,
    "name": "Tariff Profile 2",
    "description": "This Tariff Profile is for testing.",
    "used_count": 0,
    "tariff": {
      "id": 2,
      "name": "Tariff 2",
      "description": "Tariff only for testing.",
      "created": "2014-10-20 00:00:00",
      "tariff_status_id": "2",
      "currency_id": "1",
      "default_sms_mt_rate": 0,
      "default_sms_mo_rate": 0,
      "sim_issued_rate": 0,
      "sim_activated_rate": 0,
      "sim_suspended_rate": 0,
      "sim_activation_rate": 0,
      "sim_reactivation_rate": 0,
      "sim_suspension_rate": 0,
      "sim_termination_rate": 0,
      "currency": {
        "id": 1,
        "code": "EUR",
        "symbol": "€"
      },
      "data_blocksize": {
        "id": 1,
        "description": "exact",
        "octets": 1
      },
      "data_throttle": {
        "id": 1,
        "description": "256 kbit/s",
        "octets": 256000
      },
      "pdp_context_definition": [
        {
          "id": 22,
          "apn": "internet.mno.com",
          "default": false
        }
      ]
    }
  }
]
Create Tariff Profile
/api/v1/tariff_profile

Create the specified tariff profile

ID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • name (String required)

  • description (String optional)

  • tariff (Object required)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "new TP name",
  "description": "new TP description",
  "tariff": {
    "id": 2
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/tariff_profile/42

Single Tariff Profile Operations 

Retrieve Tariff Profile
/api/v1/tariff_profile/{id}

Returns tariff profile specified by id. This tariff profile also contains information about the currently valid ratezones of the tariff in the tariff profile and if the ratezone is selected in the tariff profile.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 1,
  "name": "Tariff Profile 1",
  "description": "This Tariff Profile is for testing.",
  "used_count": 56,
  "tariff": {
    "id": 1,
    "name": "Tariff 1",
    "description": "Tariff only for testing.",
    "created": "2014-10-20 00:00:00",
    "status": {
      "id": 1,
      "description": "Active"
    },
    "default_sms_mt_rate": 0.06,
    "default_sms_mo_rate": 0.06,
    "sim_issued_rate": 0,
    "sim_activated_rate": 1,
    "sim_suspended_rate": 0,
    "sim_activation_rate": 0,
    "sim_reactivation_rate": 0.5,
    "sim_suspension_rate": 0.5,
    "sim_termination_rate": 0,
    "currency": {
      "id": 1,
      "code": "EUR",
      "symbol": "€"
    },
    "data_blocksize": {
      "id": 1,
      "description": "exact",
      "octets": 1
    },
    "data_throttle": {
      "id": 1,
      "description": "256 kbit/s",
      "octets": 256000
    },
    "pdp_context_definition": [
      {
        "id": 12,
        "apn": "internet.test.com",
        "default": true
      }
    ]
  },
  "ratezone": [
    {
      "id": 1,
      "tariff_id": "1",
      "name": "Zone 1",
      "ratezone_status_id": "0",
      "valid_from": "2015-05-20 10:00:00",
      "valid_until": null,
      "status": {
        "id": 1,
        "description": "Active"
      },
      "rate": [
        {
          "ratezone_rate_id": "1",
          "ratezone_id": "1",
          "rate": "0.150000",
          "currency_id": "1",
          "volume": "1.000000",
          "valid_from": "2015-01-07 09:14:25",
          "valid_until": null,
          "service_id": "38",
          "currency": {
            "code": "EUR",
            "symbol": "€",
            "id": 1
          },
          "service": {
            "id": 38,
            "description": "All Data Services",
            "parent_service_id": "1",
            "traffic_type_id": "5",
            "teleservice_code": "112",
            "used_with_vlr": "0",
            "used_with_sgsn": "1",
            "visible": "1",
            "traffic_type": {
              "description": "Data",
              "unit": "MB",
              "id": 5
            }
          }
        }
      ],
      "selected": true
    }
  ]
}
Patch Tariff Profile
/api/v1/tariff_profile/{id}

Patch the specified tariff profile.

You can provide following fields with this request:

  • name (String optional)

  • description (String optional)

  • tariff (Object optional) If the tariff is changed, all selections of ratezones are removed.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "patched TP name",
  "description": "patched TP description",
  "tariff": {
    "id": 12
  }
}
  • Response  204
Delete Tariff Profile
/api/v1/tariff_profile/{id}

Deletes tariff profile. Tariff profiles used by an endpoint (used_count>0) cannot be deleted.

  • Parameters
  • id
    number (required) 

    tariff profile ID

  • Response  204

Ratezone Selection 

Add Ratezone to Tariff Profile
/api/v1/tariff_profile/{tp_id}/ratezone_selection/{rz_id}

Only currently valid and active ratezones can be selected for a tariff profile

  • Parameters
  • tp_id
    number (required) 

    tariff profile ID

    rz_id
    number (required) 

    ratezone ID

  • Response  204
Remove Ratezone from Tariff Profile
/api/v1/tariff_profile/{tp_id}/ratezone_selection/{rz_id}

Remove previously selected ratezones from a tariff profile

  • Parameters
  • tp_id
    number (required) 

    tariff profile ID

    rz_id
    number (required) 

    ratezone ID

  • Response  204

Tariff Profile Coverage 

Retrieve Coverage
/api/v1/tariff_profile/{tp_id}/coverage

Provides the list of countries where that tariff profile can be used.

  • Parameters
  • tp_id
    number (required) 

    tariff profile ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "country": {
      "id": 1,
      "name": "Germany"
    },
    "redundancy_count": 2
  },
  {
    "country": {
      "id": 2,
      "name": "Italy"
    },
    "redundancy_count": 1
  }
]

Tariff Plans 

This section describes available API services for managing tariff plan resources. The API provides services to retrieve the collection of tariff plans or a single tariff plan, as well as CRUD operations via POST, GET, PATCH and DELETE actions.

Below is a sample tariff plan in JSON representation.

{
  "id": 1,
  "name": "Evaluation Plan",
  "description": "Plan for first-time customers, including 3 SIMs per month",
  "status": {
    "id": 2,
    "description": "Deprecated"
  },
  "deprecation_date": "2016-01-20 00:00:00",
  "min_runtime": {
    "id": 12,
    "number_of_units": 12,
    "unit":{
      "id": 1,
      "name": "month"
    }
  },
  "payment":[
    {
      "id": 2,
      "interval": {
        "id": 1,
        "name": "month"
      },
      "amount": 29.99,
      "currency": {
        "id":1,
        "code": "EUR",
        "symbol": "€"
      }
    },
    {
      "id": 5,
      "interval": {
        "id": 2,
        "name": "contract term"
      },
      "amount": 450.00,
      "currency": {
        "id":1,
        "code": "EUR",
        "symbol": "€"
      }
    }
  ]
}

Description of Tariff Plan Properties

Here is the description of the tariff plan object:

Name Type Description
id Integer Unique ID of this tariff plan
name String short name of this tariff plan
description String long description of this tariff plan
status Object the status of this tariff plan
owner_organisation Object the organisation that owns the tariff plan
deprecation_date Date Date when the tariff plan became deprecated
min_runtime Object minimum running duration for this tariff plan
payment Object list of available payment schemes for this tariff plan

Single Tariff Plan Operations 

Retrieve the selected tariff plan
/api/v1/organisation/{orgId}/tariff_plan/selected

Returns currently selected tariff plan, its assigned tariff plan elements (with “bookings” counter) for an organisation specified by orgId.
It includes the payment information for the tariff plan and its assigned tariff plan elements (if/when any payment is configured)
This information for one’s own organisation can also be retrieved with a call to
/api/v1/organisation/my/tariff_plan/selected

  • Parameters
  • orgId
    number (required) 

    Organisation ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 1,
  "name": "Evaluation Plan",
  "description": "Plan for first-time customers",
  "status": {
    "id": 2,
    "description": "Deprecated"
  },
  "deprecation_date": "2016-01-20 00:00:00",
  "min_runtime": {
    "id": 12,
    "number_of_units": 12,
    "unit": {
      "id": 1,
      "name": "month"
    }
  },
  "payment": [
    {
      "id": 2,
      "interval": {
        "id": 1,
        "name": "month"
      },
      "amount": 29.99,
      "currency": {
        "id": 1,
        "code": "EUR",
        "symbol": "€"
      }
    }
  ],
  "elements": [
    {
      "id": 3,
      "name": "max. active SIMs per month",
      "description": "you are allowed to have up to 50 active SIMs, ...",
      "status": {
        "id": 1,
        "name": "Active",
        "description": "deployed and may be in use; changes to the configuration are limited"
      },
      "owner_organisation": {
        "id": 2,
        "name": "TPL Owner"
      },
      "min_runtime": {
        "id": 3,
        "number_of_units": 3,
        "unit": {
          "id": 0,
          "name": "month"
        }
      },
      "type": {
        "id": 1,
        "name": "batch"
      },
      "optional": false,
      "batch_size": 50
    },
    {
      "id": 13,
      "name": "additional SIM package",
      "description": "enlarge your deployment ...",
      "status": {
        "id": 1,
        "name": "Active",
        "description": "deployed and may be in use; changes to the configuration are limited"
      },
      "owner_organisation": {
        "id": 2,
        "name": "TPL Owner"
      },
      "min_runtime": {
        "id": 3,
        "number_of_units": 3,
        "unit": {
          "id": 0,
          "name": "month"
        }
      },
      "payment": [
        {
          "id": 33,
          "interval": {
            "id": 0,
            "name": "month"
          },
          "amount": 25,
          "currency": {
            "id": 1,
            "symbol": "€"
          },
          "selected": true
        }
      ],
      "type": {
        "id": 6,
        "name": "branch"
      },
      "optional": true,
      "bookings": 3
    }
  ]
}

Retrieve Available Tariff Plans 

Retrieve available tariff plans
/api/v1/organisation/{orgId}/tariff_plan

Retrieve a list of all Tariff Plans that are available for the given organisation.
The available tariff plans for one’s own organisation can also be retrieved with a call to

/api/v1/organisation/my/tariff_plan

  • Parameters
  • orgId
    number (required) 

    Organisation ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 24,
    "name": "Data Flat",
    "description": "Unlimited Data Usage, ...",
    "min_runtime": {
      "id": 18,
      "number_of_units": 18,
      "unit": {
        "id": 1,
        "name": "month"
      }
    },
    "level_shift": "Downgrade", 
    "deprecation_date": "2018-05-20 00:00:00",
    "payment": [{
        "id": 2,
        "interval": {
            "id": 1,
            "name": "month"
        },
        "amount": 29.99,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
     }, {
        "id": 5,
        "interval": {
           "id": 2,
           "name": "contract term"
        },
        "amount": 450.00,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }],
    "elements": [
      {
        "id": 3,
        "name": "max. active SIMs per month",  
        "description": "some description",                    
        "optional": false
      },
      {
        "id": 13,
        "name": "additional SIM package",
        "description": "some description",
        "optional": true,
        "payment": [{
          "id": 2,
          "interval": {
            "id": 1,
            "name": "month"
          },
          "amount": 29.99,
          "currency": {
            "id": 1,
            "symbol": "€"
          }
        }],
      }
    ]
  },
  {
    "id": 28,
    "name": "Data Flat & SMS Flat",
    "description": "Unlimited Data Usage and SMS Flat ...",
    "min_runtime": {
      "id": 24,
      "number_of_units": 24
      "unit": {
        "id": 1,
        "name": "month"
      }
    },
    "level_shift": "Upgrade", 
    "payment": [{
        "id": 2,
        "interval": {
            "id": 1,
            "name": "month"
        },
        "amount": 39.99,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }, {
        "id": 5,
        "interval": {
            "id": 2,
            "name": "contract term"
        },
        "amount": 800.00,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }],
    "elements": [
      {
        "id": 3,
        "name": "max. active SIMs per month",  
        "description": "some description",                    
        "optional": false
      }
    ]
  }
]

Retrieve Single Available Tariff Plan 

Retrieve the details for an available tariff plan
/api/v1/organisation/{orgId}/tariff_plan/{tariffPlanId}

Retrieve detailed information for a Tariff Plan that is available for a specific Organisation The available tariff plan details for one’s own organisation can also be retrieved with a call to /api/v1/organisation/my/tariff_plan/{tariffPlanId}

  • Parameters
  • orgId
    number (required) 

    Organisation ID

    tariffPlanId
    number (required) 

    Tariff Plan ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
    "id": 24,
    "name": "Data Flat",
    "description": "Unlimited Data Usage, ...",
    "status": {
      "id": 1,
      "name": "Active",
      "description": "deployed and may be in use; changes to the configuration are limited"
    },
    "owner_organisation": {
      "id": 2,
      "name": "TPL Owner"
    },
    "level_shift": "Downgrade", 
    "min_runtime": {
      "id": 18,
      "number_of_units": 18,
      "unit": {
        "id": 0,
        "name": "month"
      }
    },
    "deprecation_date": "2018-05-20 00:00:00",
    "payment": [{
        "id": 2,
        "interval": {
            "id": 1,
            "name": "month"
        },
        "amount": 29.99,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
      }
    ],
    "elements": [
      {
        "id": 3,
        "name": "max. active SIMs per month",
        "description": "you are allowed to have up to 50 active SIMs, ...",
        "status": {
          "id": 1,
          "name": "Active",
          "description": "deployed and may be in use; changes to the configuration are limited"
        },
        "owner_organisation": {
          "id": 2,
          "name": "TPL Owner"
        },
        "min_runtime": {
          "id": 3,
          "number_of_units": 3,
          "unit": {
            "id": 0,
            "name": "month"
          }
        },
        "type": {
          "id": 1,
          "name": "batch"
        },
        "optional": false,
        "batch_size": 50
      },
      {
        "id": 13,
        "name": "additional SIM package",
        "description": "enlarge your deployment ...",
        "status": {
          "id": 1,
          "name": "Active",
          "description": "deployed and may be in use; changes to the configuration are limited"
        },
        "owner_organisation": {
          "id": 2,
          "name": "TPL Owner"
        },
        "min_runtime": {
          "id": 3,
          "number_of_units": 3,
          "unit": {
            "id": 0,
            "name": "month"
          }
        },
        "payment": [
          {
            "id": 33,
            "interval": {
              "id": 0,
              "name": "month"
            },
            "amount": 25.00,
            "currency": {
              "id": 1,
              "symbol": "€"
            }
          }
        ],

        "type": {
          "id": 6,
          "name": "branch"
        },
        "optional": true,
        "duration": {
          "id": 1,
          "number_of_units": 1,
          "time_unit": {
            "id": 0,
            "name": "month"
          }
        },
        "subelements": [
          {
            "id": 42,
            "name": "50 active SIMs in SIM package",
            "description": "you may have 50 more active SIMs as part of the 'additional SIM package'",
            "min_runtime": {
              "id": 3,
              "number_of_units": 3,
              "unit": {
                "id": 0,
                "name": "month"
              }
            },
            "type": {
              "id": 1,
              "name": "batch"
            },
            "batch_size": 50,
            "optional": false
          },
          {
            "id": 43,
            "name": "100 free SMS a month",
            "description": "you get 50 free SMS along with your SIM package",
            "min_runtime": {
              "id": 3,
              "number_of_units": 3,
              "unit": {
                "id": 0,
                "name": "month"
              }
            },
            "type": {
              "id": 1,
              "name": "batch"
            },
            "duration": {
              "id": 1,
              "number_of_units": 1
              "time_unit": {
                "id": 0,
                "name": "month"
              }
            }
          }
        ]
      }
    ]
  }

Retrieve Tariff Plan Selection 

Retrieve single selections
/api/v1/organisation/{orgId}/tariff_plan_selection/{tplsId}

Retrieve a single tariff plan selection for an organisation. A Tariff Plan Selection for your own organisation can also be retrieved with a call to /api/v1/organisation/my/tariff_plan_selection/{tplsId}

  • Parameters
  • orgId
    number (required) 

    Organisation ID

    tplsId
    number (required) 

    Tariff Plan Selection ID

  • Response  200
  • Body
    {
  "id": 7,
  "tariff_plan": {
    "id": 5,
    "name": "Professional Plan",
    "description": "Professional Plan",
    "status": {
      "id": 1,
      "name": "Active"
    },
    "min_runtime": {
      "id": 1,
      "number_of_units": 1,
      "unit": {
        "id": 0,
        "name": "month"
      }
    }
  },
  "status": {
    "id": 2,
    "name": "Outdated"
  },
  "start_date": "2015-07-04",
  "expiry_date": "2015-07-05",
  "selection_date": "2015-07-01",
  "payment": [
    {
      "id": 2,
      "interval": {
        "id": 0,
        "name": "month"
      },
      "amount": 99.99,
      "currency": {
        "id": 1,
        "code": "EUR",
        "symbol": "€"
      }
    }
  ]
}

Retrieve Active Tariff Plan Selection 

Retrieve active selection
/api/v1/organisation/{orgId}/tariff_plan_selection/active

Retrieve the active tariff plan selection for an organisation. The active Tariff Plan Selection for your own organisation can also be retrieved with a call to /api/v1/organisation/my/tariff_plan_selection/active

  • Parameters
  • orgId
    number (required) 

    Organisation ID

  • Response  200
  • Body
    {
  "id": 8,
  "tariff_plan": {
    "id": 5,
    "name": "Professional Plan",
    "description": "Professional Plan",
    "status": {
      "id": 1,
      "name": "Active"
    },
    "min_runtime": {
      "id": 1,
      "number_of_units": 1,
      "unit": {
        "id": 0,
        "name": "month"
      }
    }
  },
  "status": {
    "id": 1,
    "name": "Active"
  },
  "start_date": "2016-07-04",
  "expiry_date": "2016-07-05",
  "selection_date": "2016-07-01",
  "payment": [
    {
      "id": 1,
      "interval": {
        "id": 0,
        "name": "month"
      },
      "amount": 9.99,
      "currency": {
        "id": 1,
        "code": "EUR",
        "symbol": "€"
      }
    }
  ]
}

Tariff Plan Selection 

Retrieve list of selections
/api/v1/organisation/{orgId}/tariff_plan_selection

Retrieve a list of all tariff plan selections for an organisation. The list for your own organisation can also be retrieved with a call to /api/v1/organisation/my/tariff_plan_selection

  • Parameters
  • orgId
    number (required) 

    Organisation ID

  • Response  200
  • Body
    [
  {
    "id": 1,
    "tariff_plan": {
      "id": 2,
      "name": "Evaluation",
      "status": {
        "id": 1,
        "name": "Active"
      }
    },
    "level_shift": "Upgrade",
    "status": {
      "id": 2,
      "name": "Outdated"
    },
    "start_date": "2016-01-01",
    "expiry_date": "2016-01-31"
  },
  {
    "id": 2,
    "tariff_plan": {
      "id": 3,
      "name": "Basic",
      "status": {
        "id": 1,
        "name": "Active"
      }
    },
    "level_shift": "None",
    "status": {
      "id": 1,
      "name": "Active"
    },
    "start_date": "2016-02-01",
    "expiry_date": "2016-05-30"
  },
  {
    "id": 4,
    "tariff_plan": {
      "id": 3,
      "name": "Professional",
      "status": {
        "id": 1,
        "name": "Active"
      }
    },
    "level_shift": "Upgrade",
    "status": {
      "id": 0,
      "name": "Prepared"
    },
    "start_date": "2016-06-01"
  }
]
Select Tariff Plan
/api/v1/organisation/{orgId}/tariff_plan_selection

Select the specified tariff plan for the organisation specified by the orgId parameter.
The selection of a tariff plan for one’s own organisation can also be achieved with a call to
/api/v1/organisation/my/tariff_plan_selection

You can provide following fields with this request:

  • tariff_plan (Object required)

  • start_date (Date optional) Time need not be specified as it is ignored. If given, it is truncated to the start (00:00) of the given day

  • payment (Object required) This payment must be one belonging to the given tariff_plan, otherwise a “InvalidReference” error is generated

  • Parameters
  • orgId
    number (required) 

    Organisation ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "tariff_plan": {
    "id": 3
  },
  "start_date": "2016-06-23",
  "payment": {
    "id": 13
  }
}
  • Response  201
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "TariffPlan with Id '3' not found"
}
  • Response  400
  • Body
    {
  "error_code": 1406,
  "error_token": "NotAllowed",
  "message": "Selecting Tariff Plan with id '3' for Organisation '2' not allowed"
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "TariffPlanPayment with Id '13' not found"
}

Tariff Plan Element Selection 

Select Tariff Plan Element for Active Tariff Plan
/api/v1/organisation/{orgId}/tariff_plan_selection/active/element

Select an optional Tariff Plan Element additionaly to the curently Active Tariff Plan for my own/child org

The Tariff Plan Element Selection for one’s own organisation is also available at entrypoint:
/api/v1/organisation/my/tariff_plan_selection/active/element

You can provide following fields with this request:

  • tariff_plan_element (Object required) this element should be accessible to the organisation, be “optional” (otherwise it is already booked by default) and be in “ACTIVE” status

  • start_date (Date optional) Time need not be specified as it is ignored. If given, it is truncated to the start (00:00) of the given day (default is today). It cannot be a date before the last non-billed billing period

  • payment (Object optional) This payment must be one belonging to the given tariff_plan_element, otherwise a “InvalidReference” error is generated.

  • extension_mode (Object optional) Default is the extension_mode from the tariff_plan_element assignment, otherwise default is “FORCED”

  • runtime (Object optional) Default is the runtime from the tariff_plan_element. If given, it cannot be shorter than the runtime from the tariff_plan_element

  • Parameters
  • orgId
    number (required) 

    Organisation ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "tariff_plan_element": {
    "id": 3
  },
  "start_date": "2016-06-23",
  "payment": {
    "id": 13
  },
  "extension_mode": {
    "id": 1
  },
  "runtime": {
    "id": 1
  }
}
  • Response  201
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Organisation with Id '999' not found."
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "InputValidationFailed",
  "errors": [
    {
      "error_code": 1402,
      "error_token": "Required",
      "message": "Tariff Plan Element Selection - Tariff Plan Element is required."
    }
  ]
}

Retrieve Available Tariff Plan Selection Statuses 

Retrieve Available Tariff Plan Selection Statuses
/api/v1/tariff_plan_selection/status

Provides the list of available Tariff Plan Selection status (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "name": "Prepared"
  },
  {
    "id": 1,
    "name": "Active"
  },
  {
    "id": 2,
    "name": "Outdated"
  },
  {
    "id": 3,
    "name": "Skipped"
  }
]

Tariff Plan Status 

List of available Tariff Plan Statuses
/api/v1/tariff_plan/status

Retrieve a list of tariff plan statuses.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "name": "Staging",
    "description": "under construction and therefore not ready to be used; any changes of the configuration are allowed"
  },
  {
    "id": 1,
    "name": "Active"
    "description": "deployed and may be in use; changes to the configuration are limited"
  },
  {
    "id": 2,
    "name": "Deprecated"
    "description": "not assignable anymore but remains valid for current assignments and therefore may be still in use; changes to the configuration are limited"
  },
  {
    "id": 3,
    "name": "Deleted"
    "description": "not visible to maintainers and users, but is displayed in history view, no changes to the configuration are allowed"
  }
]

Tariff Plan Config 

These API calls are used to retrieve and manage Tariff Plans and other Tariff Plan related settings.

Beside the fields explained in the tariff plan section, this entrypoint provides some additional information:

Name Type Description
level Number level of a tariff plan to indicate if a change to a tariff plan would mean an upgrade or a downgrade
public_for_child_organisations Boolean Indicates if the tariff plan will be listed as available tariff plan for child organisations
creation_date Date Date when the tariff plan was created
activation_date Date Date when the tariff plan status was changed to active
notes String Possibility to store some information about that tariff plan
used_count Number The count how often the tariff plan is in an active or prepared selection

Retrieve Configured Tariff Plans 

Retrieve configured tariff plans
/api/v1/tariff_plan_config?{q}{page}{per_page}{sort}

Retrieve a list of all configured Tariff Plans of my own or my organisations, filtered, sorted and paged according to query parameters.

  • Parameters
  • q
    String (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields,
    id,
    status,
    description,
    name,
    level,
    min_runtime,
    organisation,
    public_for_child_organisations,
    creation_date,
    activation_date,
    deprecation_date,
    notes.

    Example q=status:1,organisation:2

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields,
    id,
    status,
    description,
    name,
    level,
    min_runtime,
    organisation,
    public_for_child_organisations,
    creation_date,
    activation_date,
    deprecation_date,
    notes.

    Example sort=-status,id
    Sort by status descending and id ascending
    Default sorting is by organisation and name!

  • Response  200
  • Headers
    Content-Type: application/json
    Link: <https://cdn.emnify.net/api/v1/tariff_plan_config?q=status:1&per_page=2&sort=id>; rel="first", <https://cdn.emnify.net/api/v1/tariff_plan_config?q=status:1&page:2&per_page=2&sort=id>; rel="prev", <https://cdn.emnify.net/api/v1/tariff_plan_config?q=status:1&page:4&per_page=2&sort=id>; rel="next", <https://cdn.emnify.net/api/v1/tariff_plan_config?q=status:1&page:5&per_page=2&sort=id>; rel="last"
    X-Count-Per-Page: 2
    X-Current-Page: 3
    X-Filter: status:1
    X-Sort: id
    X-Total-Count: 10
    X-Total-Pages: 5
    Body
    [
  {
    "id": 24,
    "name": "Data Flat",
    "description": "Unlimited Data Usage, ...",
    "status":{
      "id": 1,
      "name": "Active"
    },
    "public_for_child_organisations":false,
    "owner_organisation":{
      "id": 1,
      "name": "Own Organisation"
    },
    "min_runtime": {
      "id": 18,
      "number_of_units": 18,
      "unit": {
        "id": 1,
        "name": "month"
      }
    },
    "deprecation_date": "2018-05-20T00:00:00",
    "payment": [{
        "id": 2,
        "interval": {
            "id": 1,
            "name": "month"
        },
        "amount": 29.99,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }, {
        "id": 5,
        "interval": {
           "id": 2,
           "name": "contract term"
        },
        "amount": 450.00,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }],
    "elements": [
      {
        "id": 3,
        "name": "max. active SIMs per month", 
        "status": {
          "id": 1,
          "name": "Active",
          "description": "deployed and may be in use; changes to the configuration are limited"
        }, 
        "optional": false
      },
      {
        "id": 13,
        "name": "additional SIM package",
        "status": {
          "id": 1,
          "name": "Active",
          "description": "deployed and may be in use; changes to the configuration are limited"
        },
        "optional": true
      }
    ]
  },
  {
    "id": 28,
    "name": "Data Flat & SMS Flat",
    "description": "Unlimited Data Usage and SMS Flat ...",
    "status": {
      "id": 1,
      "name": "Active"
    },
    "public_for_child_organisations": true,
    "owner_organisation":{
      "id": 2,
      "name": "Child Organisation"
    },
    "min_runtime": {
      "id": 24,
      "number_of_units": 24
      "unit": {
        "id": 1,
        "name": "month"
      }
    },
    "payment": [{
        "id": 2,
        "interval": {
            "id": 1,
            "name": "month"
        },
        "amount": 39.99,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }, {
        "id": 5,
        "interval": {
            "id": 2,
            "name": "contract term"
        },
        "amount": 800.00,
        "currency": {
            "id": 1,
            "symbol": "€"
        }
    }],
    "elements": [
      {
        "id": 8,
        "name": "100 additional active sims", 
        "status": {
          "id": 1,
          "name": "Active",
          "description": "deployed and may be in use; changes to the configuration are limited"
        }, 
        "optional": true
      }
    ]
  }
]

Tariff Plan Creation 

Create Tariff Plan
/api/v1/tariff_plan_config

Create the specified tariff plan

ID must not be specified, neither in query String, nor in JSON payload.

You can provide following fields with this request:

  • name (String required)

  • description (String optional)

  • notes (String optional)

  • min_runtime (Object required)

  • level (Number optional, default: 100)

  • public_for_child_organisations (boolean optional, default: false)

  • organisation (Object optional, default: own organisation)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "Starter Plan",
  "description": "Use 5 SIM cards to test the product",
  "notes": "Internal notes",
  "min_runtime": {
    "id": 3
  },
  "level": 100,
  "organisation": {
    "id": 23
  },
  "public_for_child_organisations": true
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/tariff_plan_config/42
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "A Tariff Plan or a Tariff Plan Element with name - Starter Plan already exists."
}

Single Configured Tariff Plan Operations 

Retrieve Configured Tariff Plan
/api/v1/tariff_plan_config/{id}

Returns the details for a configured tariff plan owned by yourself or one of your children.

  • Parameters
  • id
    number (required) 

    Tariff Plan ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
        "id": 24,
        "name": "Data Flat",
        "description": "Unlimited Data Usage, ...",
        "status": {
          "id": 1,
          "name": "Active"
        },
        "public_for_child_organisations": false,
        "owner_organisation": {
          "id": 1,
          "name": "Own Organisation"
        },
        "level": 42,
        "min_runtime": {
          "id": 18,
          "number_of_units": 18,
          "unit": {
            "id": 0,
            "name": "month"
          }
        },
        "creation_date": "2015-05-20T00:00:00",
        "activation_date": "2015-05-25T00:00:00",
        "deprecation_date": "2018-05-20T00:00:00",
        "payment": [{
            "id": 2,
            "interval": {
                "id": 1,
                "name": "month"
            },
            "amount": 29.99,
            "currency": {
                "id": 1,
                "symbol": "€"
            }
        }],
        "notes":"some additional internal info about this tariff plan",
        "used_count":13,
        "elements": [
          {
            "id": 3,
            "name": "max. active SIMs per month",
            "description": "you are allowed to have up to 50 active SIMs, ...",
            "status": {
              "id": 1,
              "name": "Active",
              "description": "deployed and may be in use; changes to the configuration are limited"
            },
            "public_for_child_organisations": true,
            "level": 789,
            "owner_organisation": {
              "id": 2,
              "name": "TPL Owner"
            },
            "creation_date": "2015-05-20T00:00:00",
            "activation_date": "2015-05-25T00:00:00",
            "min_runtime": {
              "id": 3,
              "number_of_units": 3,
              "unit": {
                "id": 0,
                "name": "month"
              }
            },
            "type": {
              "id": 1,
              "name": "batch"
            },
            "optional": false,
            "batch_size": 50
          },
          {
            "id": 13,
            "name": "additional SIM package",
            "description": "enlarge your deployment ...",
            "status": {
              "id": 1,
              "name": "Active",
              "description": "deployed and may be in use; changes to the configuration are limited"
            },
            "public_for_child_organisations": true,
            "level": 789,
            "owner_organisation": {
              "id": 2,
              "name": "TPL Owner"
            },
            "creation_date": "2015-05-20T00:00:00",
            "activation_date": "2015-05-25T00:00:00",
            "min_runtime": {
              "id": 3,
              "number_of_units": 3,
              "unit": {
                "id": 0,
                "name": "month"
              }
            },
            "payment": [
              {
                "id": 33,
                "interval": {
                  "id": 0,
                  "name": "month"
                },
                "amount": 25.00,
                "currency": {
                  "id": 1,
                  "symbol": "€"
                }
              }
            ],
            "type": {
              "id": 6,
              "name": "branch"
            },
            "optional": true,
            "extension_mode": {
              "id": 1,
              "name": "allowed",
              "description": "after exceeding limit or the duration of these element the subscription won't be prolonged automatically but the user is allowed to book same element again; also multiple bookings of the these element at the same time are allowed; example: \"license for 10 user creations\" or similar"
            },
            "duration": {
              "id": 1,
              "number_of_units": 1,
              "time_unit": {
                "id": 0,
                "name": "month"
              }
            },
            "subelements": [
              {
                "id": 42,
                "name": "50 active SIMs in SIM package",
                "description": "you may have 50 more active SIMs as part of the 'additional SIM package'",
                "min_runtime": {
                  "id": 3,
                  "number_of_units": 3,
                  "unit": {
                    "id": 0,
                    "name": "month"
                  }
                },
                "type": {
                  "id": 1,
                  "name": "batch"
                },
                "batch_size": 50,
                "optional": false
              },
              {
                "id": 43,
                "name": "100 free SMS a month",
                "description": "you get 50 free SMS along with your SIM package",
                "min_runtime": {
                  "id": 3,
                  "number_of_units": 3,
                  "unit": {
                    "id": 0,
                    "name": "month"
                  }
                },
                "type": {
                  "id": 1,
                  "name": "batch"
                },
                "duration": {
                  "id": 1,
                  "number_of_units": 1
                  "time_unit": {
                    "id": 0,
                    "name": "month"
                  }
                }
              }
            ]
          }
        ]
    }
Update Tariff Plan
/api/v1/tariff_plan_config/{id}

Update a tariff plan.

You may provide following fields with this request if the Tariff Plan is in Status Staging:

  • name (String optional)

  • description (String optional)

  • notes (String optional)

  • level (Integer optional)

  • public_for_child_organisations (Boolean optional)

  • min_runtime (Object optional)

  • status (Object optional)

  • organisation (Object optional)

Once the tariff plan is in status active or deprecated, neither the organisation nor the min_runtime may be changed anymore. Also changing the status back to Staging or changing the status from Deprecated to Active is not possible.

NOTE:
Updating the Status to Active is only allowed if these conditions are met:

  • at least one payment is configured for this Tariff Plan

  • any tariff plan elements assigned to this tariff plan must be already in Active status

  • Parameters
  • id
    number (required) 

    Tariff Plan ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "new name",
  "description": "new description",
  "notes": "new notes",
  "level": 42,
  "public_for_child_organisations": true,
  "min_runtime": {
    "id": 1
  },
  "status": {
    "id": 1
  },
  "organisation": {
    "id": 47
  }
}
  • Response  204
  • Response  400
  • Headers
    Content-Type: application/json
    Body
    {
  "error_code": 1406,
  "error_token": "NotAllowed",
  "message": "Activating a tariff plan without payments not allowed."
}
Delete Tariff Plan
/api/v1/tariff_plan_config/{id}

Deletes a tariff plan. If it is selected by an organisation (already active or prepared for future use) deletion will be rejected.

  • Parameters
  • id
    number (required) 

    Tariff Plan ID

  • Response  204
  • Response  409
  • Headers
    Content-Type: application/json
    Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Cannot delete Tariff Plan that is used in an active or prepared selection."
}

Tariff Plan Payments 

Tariff Plan Payments config
/api/v1/tariff_plan_config/{tariff_plan_id}/payment

Returns the payment options configured for a specific tariff plan.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
       {
           "id": 0,
           "interval":{
               "id": 1,
               "name": "month"
           },
           "amount": 29.0,
           "currency": {
               "id": 1,
               "code": "EUR",
               "symbol": "€"
           }
       },
       {
           "id": 1,
           "interval": {
               "id": 2
               "name": "contract term"
           },
           "amount": 290.0,
           "currency": {
               "id": 1,
               "code": "EUR",
               "symbol": "€"
           }
       }
   ]
Create Tariff Plan Payments
/api/v1/tariff_plan_config/{tariff_plan_id}/payment

Create and assign a Payment to a specific Tariff Plan. Only allowed for Tariff Plans in status “STAGING”.

You need to provide following fields with this request:

  • interval (Object required)

  • amount (Double required)

  • currency (Object required)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "interval": {
    "id": 0
  },
  "amount": 55.55,
  "currency": {
    "id": 1
  }
}
  • Response  201
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "Tariff Plan Payment Interval - month already exists."
}

Tariff Plan Payment 

Delete Tariff Plan Payment
/api/v1/tariff_plan_config/{tariff_plan_id}/payment/{payment_id}

Delete a payment option configured for a specific tariff plan. Only allowed for Tariff Plans in status “STAGING”.

  • Response  204
  • Response  409
  • Headers
    Content-Type: application/json
    Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Cannot delete Tariff Plan Payment that is used on an Active Tariff Plan."
}

Tariff Plan Payment Intervals 

List of Payment Intervals
/api/v1/tariff_plan_config/payment/interval

Returns the available intervals to choose in tariff plan payments.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "name": "month"
  },
  {
    "id": 1,
    "name": "contract term"
  }
]

Tariff Plan Runtimes 

List of Runtimes
/api/v1/tariff_plan_config/runtime

Returns the available runtimes to choose from.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "number_of_units": 1,
    "unit": {
      "id": 0,
      "name": "month"
    }
  },
  {
    "id": 2,
    "number_of_units": 6,
    "unit": {
      "id": 0,
      "name": "month"
    }
  },
  {
    "id": 4,
    "number_of_units": 18,
    "unit": {
      "id": 0,
      "name": "month"
    }
  },
  {
    "id": 3,
    "number_of_units": 1,
    "unit": {
      "id": 1,
      "name": "year"
    }
  },
  {
    "id": 5,
    "number_of_units": 2,
    "unit": {
      "id": 1,
      "name": "year"
    }
  }
]

Tariff Plan Extension Modes 

List of available Tariff Plan Extension Modes
/api/v1/tariff_plan_config/extension_mode

Retrieve a list of tariff plan extension modes.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "name": "not allowed",
    "description": "after exceeding a limit or the duration of that element no further usage of the service of that element is possible; it is not possible to book this element multiple times; example: \"Welcome offer: 50 free SIM activations for setup\" or similar"
  },
  {
    "id": 1,
    "name": "allowed",
    "description": "after exceeding limit or the duration of these element the subscription won't be prolonged automatically but the user is allowed to book same element again; also multiple bookings of the these element at the same time are allowed; example: \"license for 10 user creations\" or similar"
  },
  {
    "id": 2,
    "name": "forced",
    "description": "when an overrun of a limit or the duration of that element takes place, an extension of that element subscription follows automatically; example: \"optional 50 active SIMS\" or similar"
  },
  {
    "id": 3,
    "name": "limit allowed",
    "description": "after exceeding limit of these element the subscription won't be prolonged automatically but the user is allowed to book same element again; also multiple bookings of the these element at the same time are allowed;"
  },
  {
    "id": 4,
    "name": "duration allowed",
    "description": "after exceeding duration of these element the subscription won't be prolonged automatically but the user is allowed to book same element again; also multiple bookings of the these element at the same time are allowed;"
  },
  {
    "id": 5,
    "name": "limit forced",
    "description": "when an overrun of a limit of that element takes place, an extension of that element subscription follows automatically;"
  },
  {
    "id": 6,
    "name": "duration forced",
    "description": "after exceeding the duration of that element, an extension of that element subscription follows automatically;"
  },
  {
    "id": 7,
    "name": "limit allowed duration forced",
    "description": "if the duration of these element gets exceeded an extension of that element takes place automatically; if the limit gets exceeded the subscription won't be prolonged automatically but the user is allowed to book same element again; also multiple bookings of the these element at the same time are allowed;"
  },
  {
    "id": 8,
    "name": "duration allowed limit forced",
    "description": "if the limit of these element gets exceeded an extension of that element takes place automatically; if the duration gets exceeded the subscription won't be prolonged automatically but the user is allowed to book same element again; also multiple bookings of the these element at the same time are allowed;"
  }
]

Tariff Plan Element Creation 

Create Tariff Plan Element
/api/v1/tariff_plan_config/element

Create the specified tariff plan element

ID must not be specified, neither in query String, nor in JSON payload. The combination of name and organisation_id is to be unique, else a “Duplicated” error may result.

You can provide following fields with this request:

  • name (String required)

  • type (Object required)

  • description (String optional)

  • level (Number optional, default: 100)

  • public_for_child_organisations (boolean optional, default: false)

  • min_runtime (Object optional, default: 1 month)

  • notes (String optional)

  • batch_size (Number optional)

  • duration (Object optional)

  • min_limit (Number optional)

  • max_limit (Number optional)

  • organisation (Object optional, default: own organisation)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "additional 10000 SMS yearly batch",
  "level": 123,
  "public_for_child_organisations": true,
  "min_runtime": {
    "id": 12
  },
  "notes": "notes about the 10000 SMS yearly batch",
  "type": {
    "id": 1
  },
  "batch_size": 10000,
  "duration": {
    "id": 4
  },
  "min_limit": 10000,
  "max_limit": 10000,
  "organisation": {
    "id": 23
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/tariff_plan_config/element/422
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "A Tariff Plan or a Tariff Plan Element with name - additional 10000 SMS yearly batch already exists."
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "InputValidationFailed",
  "errors": [
    {
      "error_code": 1408,
      "error_token": "InvalidValue",
      "message": "Tariff Plan Element - min_limit is invalid: Must not be greater than max_limit."
    }
  ]
}

Single Tariff Plan Element Operations 

Retrieve Tariff Plan Element
/api/v1/tariff_plan_config/element/{id}

Returns Tariff Plan Element specified by id. The Tariff Plan Element details may also contain information about subelements, when so configured.

  • Parameters
  • id
    number (required) 

    Tariff Plan Element ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
    "id": 124,
    "name": "dedicated APN",
    "description": "element for APN maintainance, 150 € monthly",
    "status": {
      "id": 1,
      "name": "Active"
    },
    "public_for_child_organisations": false,
    "type": {
      "id": 6,
      "name": "Branch"
    },
    "owner_organisation": {
      "id": 11,
      "name": "Own Organisation"
    },
    "level": 333, 
    "min_runtime": {
      "id": 2,
      "number_of_units": 3,
      "unit": {
        "id": 0,
        "name": "month"
    },
    "creation_date": "2015-05-27T00:00:00",
    "activation_date": "2015-05-28T00:00:00",
    "payment": [],
    "notes": "element for APN notes ...",
    "min_limit": 1,
    "max_limit": 3,
    "duration": {
        "id": 5,
        "number_of_units": 1,
        "unit": "year"
    },
    "subelements": [
        {
            "id": 125,
            "name": "apn setup",
            "type": {
                "id": 5,
                "name": "one_time"
            },
            "payment":[
                {
                  "id": 2,
                  "interval": {
                    "id": 1,
                    "name": "contract term"
                  },
                  "amount": 500,
                  "currency": {
                    "id": 1,
                    "symbol": "€"
                  }
                }
            ],
            ...
        },
        {
            "id": 126,
            "name": "apn service",
            "type": {
                "id": 4,
                "name": "service"
            },
            "payment":[
                {
                  "id": 3,
                  "interval": {
                    "id": 0,
                    "name": "month"
                  },
                  "amount": 150,
                  "currency": {
                    "id": 1,
                    "symbol": "€"
                  }
                }
            ]
        ...
        }
    ]
}
Update Tariff Plan Element
/api/v1/tariff_plan_config/element/{id}

Update a tariff plan element.

You may update the following fields with this request if the tariff plan element is in status Staging:

  • name (String optional)

  • type (Object optional)

  • description (String optional)

  • status (Object optional)

  • level (Number optional)

  • public_for_child_organisations (boolean optional)

  • min_runtime (Object optional)

  • notes (String optional)

  • batch_size (Number optional)

  • duration (Object optional)

  • min_limit (Number optional)

  • max_limit (Number optional)

  • organisation (Object optional)

Once the tariff plan element is in status Active or Deprecated, only these fields may be changed anymore: name, description, level, public_for_child_organisations, notes.
Patching the status to Deprecated is always allowed from either Staging or Active.
But changing the status backwards from Active to Staging or from Deprecated to any other status is not possible.

NOTE: Updating the Status to Active is NOT allowed if the Element Type is “Batch” and the batch size has not been defined! This would generate the error:
“Activating a TariffPlanElement of type Batch without batch_size not allowed.”

  • Parameters
  • id
    number (required) 

    Tariff Plan Element ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "new name",
  "description": "new description",
  "status": {
    "id": 1
  },
  "level": 42,
  "min_runtime": {
    "id": 1
  },
  "public_for_child_organisations": true,
  "type": {
    "id": 4
  },
  "duration": {
    "id": 3
  },
  "min_limit": 100,
  "max_limit": 200,
  "notes": "new notes"
}
  • Response  204
  • Response  422
  • Headers
    Content-Type: application/json
    Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "InputValidationFailed",
  "errors": [
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'min_runtime' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'duration' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'organisation' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'batch_size' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'min_limit' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'max_limit' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Updating the value of 'type' of an Active Tariff Plan Element not allowed."
    },
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "Patching the status of an Active Tariff Plan Element to Staging not allowed."
    }
  ]
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "TariffPlanElement with Id '999999' not found"
}

Tariff Plan Element Types 

List of available Tariff Plan Element Types
/api/v1/tariff_plan_config/element/type

Retrieve a list of tariff plan element types.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "name": "batch",
    "description": "for elements which get paid per batch. The service of these element instance gets unusable when the usage counter exceeds the batch size. The pricing (if any) refers only to the batch size and is independent of the actual counter. Example: \"50 free SMS\" or \"20 active SIMs per month\". Duration and exension mode are configurable."
  },
  {
    "id": 2,
    "name": "count",
    "description": "for elements which get paid per item. The service of these element instance gets unusable when the usage counter gets below/over the Min/Max value (if any). The pricing (if any) refers to the counter. Example with no min/max values: \"sending SMS\" or \"SIM activation Fee\", with min. value: \"sending SMS, min. 1000 per month\""
  },
  {
    "id": 3,
    "name": "rate",
    "description": "for elements which get paid per count. The service of these element instance gets unusable when the usage counter gets below/over the Min/Max value (if any). The pricing (if any) refers to the counter. Example \"technical support, operation\" or \"technical support, dedicated engeener, up to 8 hours per month\""
  },
  {
    "id": 4,
    "name": "service",
    "description": "for elements whose service can only be enabled or disabled, example: \"Connectivity - Voice\""
  },
  {
    "id": 5,
    "name": "one time",
    "description": "for elements which provide an one-time-service, example: \"Private APN set up\" or \"registration fee\", extension is not possible",
    "extension_mode": {
      "id": 0,
      "name": "not_allowed"
    }
  },
  {
    "id": 6,
    "name": "branch",
    "description": "for elements which contain other element, example: \"Private APN\" frames the elements \"Private APN set up\" (with type \"ONE_TIME\") and \"Private APN usage\" (with type \"ENABLED\")"
  }
]

Tariff Plan Element Duration 

List of Tariff Plan Element Duration
/api/v1/tariff_plan_config/element/duration

Retrieve a list of possible tariff plan element durations.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "number_of_units": 1,
    "unit": "month"
  },
  {
    "id": 2,
    "number_of_units": 3,
    "unit": "month"
  },
  {
    "id": 3,
    "number_of_units": 6,
    "unit": "month"
  },
  {
    "id": 4,
    "number_of_units": 1,
    "unit": "year"
  },
  {
    "id": 5,
    "number_of_units": 2,
    "unit": "year"
  }
]

Tariff Plan Element Assignment 

Assign Element to a Tariff Plan
/api/v1/tariff_plan_config/{tplId}/element/{elementId}

Assign an active or staging Tariff Plan Element to a staging Tariff Plan

Editable fields in Json:

  • optional (mandatory): if the element is always included in the tariff plan (false) or selectable by the user (true)

  • extension_mode (optional): extension mode can be set if no extension mode is defined in type of element

  • Parameters
  • tplId
    number (required) 

    the id of the tariff plan

    elementId
    number (required) 

    the id of the tariff plan element

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "optional": true,
  "extension_mode": {
    "id": 3
  }
}
  • Response  204
  • Response  400
  • Body
    {
  "error_code": 1406,
  "error_token": "NotAllowed",
  "message": "Setting the extension mode for a Tariff Plan Element with type 'one time' not allowed."
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "TariffPlan with Id '1111' not found."
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "InputValidationFailed",
  "errors": [
    {
      "error_code": 1402,
      "error_token": "Required",
      "message": "TariffPlanElementAssignment - optional is required."
    }
  ]
}
Delete Element Assignment from Tariff Plan
/api/v1/tariff_plan_config/{tplId}/element/{elementId}

Remove the assignment of a Tariff Plan Element from a staging Tariff Plan

  • Parameters
  • tplId
    number (required) 

    the id of the tariff plan

    elementId
    number (required) 

    the id of the tariff plan element

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Assignment of Tariff Plan Element with Id '42' for Tariff Plan with Id '12' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Cannot delete Tariff Plan Element Assignment that is used on an Active Tariff Plan."
}

Service Profiles and Traffic Limits 

Service profile is an endpoint configuration entity that groups services and traffic limits for easy assignment. Instead of assigning services and traffic limits directly to an endpoint, those can be associated to a service profile and assigned to an endpoint in single solution. Service profile holds a collection of services and for each associated service it is possible to assign zero or more traffic limits. To define traffic limits it is first necessary to associate services to a profile.

  • Services are read only objects.
  • Traffic limits are defined for a particular service
  • Traffic limits can also be associated directly to an endpoint

Typical workflow for service profile definition is:

  1. [POST] Create a service profile

  2. [PUT] Add service(s) to a profile (service collection)

  3. [PUT] Add traffic limit(s) to a service (traffic_limit collection)

For Service profile management paging, filtering and sorting is NOT provided.

Here is the sample of a service profile and description of the properties.

[
  {
    "id": 1,
    "name": "Smart meter",
    "description": "Data + SMS - 1G limit",
    "allowed_3g": true,
    "allowed_4g": false,
    "used_count":12,
    "api_callback":{
      "id":38,
      "url": "https://www.customers-server.com",
      "created": "2015-03-18 16:11:07",
      "purpose": "Customer's Webserver"
    },
    "api_secret":{
      "id": 38,
      "purpose": "K3"
    },
    "moc_callback":{
      "id":39,
      "url": "https://moc.customers-server.com",
      "created": "2015-03-18 16:11:17",
      "purpose": "Customer's Moc server"
    },
    "service": [
      {
        "id": 123,
        "description": "Data",
        "teleservice_code": 7678345,
        "used_with_vlr": true,
        "used_with_sgsn": true,
        "traffic_type": {
          "id": 1,
          "description": "Data",
          "unit": "GB"
        },
        "traffic_limit": [
          {
            "id": 123,
            "volume": 64,
            "period": {
              "id": 33,
              "time_units": 5,
              "unit": "Days"
            }
          },
          {
            "id": 234,
            "volume": 128,
            "period": {
              "id": 35,
              "time_units": 1,
              "unit": "Months"
            }
          }
        ]
      },
      {
        "id": 234,
        "description": "SMS",
        "teleservice_code": 441236,
        "used_with_vlr": true,
        "used_with_sgsn": true,
        "traffic_type": {
          "id": 2,
          "description": "SMS",
          "unit": "count"
        },
        "traffic_limit": []
      }
    ]
  }
]

Here is the description of a Service Profile object:

Name Type Description
id Integer Unique ID of this service profile
name String Short description (e.g… for select boxes)
description String Full description
allowed_3g Boolean Is 3G allowed
allowed_4g Boolean Is 4G allowed
used_count Integer The number of endpoints using this service profiles
api_callback Object id (Integer) - api_callback ID
url (String) - The URL of the api_callback
purpose (String) - The purpose of the api_callback
created (Date) - Creation Timestamp
api_secret Object id (Integer) - api_secret ID
purpose (String) - The purpose of the api_secret
moc_callback Object id (Integer) - api_callback ID
url (String) - The URL of the moc_callback
purpose (String) - The purpose of the moc_callback
created (Date) - Creation Timestamp
service Collection
(Service)		 Collection of services associated (nested) to a profile

Here is the description of a (nested) Service object:

Name Type Description
id Integer Unique ID of this service
description String Description of a service
teleservice_code Integer Teleservice code of a service
used_with_vlr Boolean
used_with_sgsn Boolean
traffic_type Object id (Integer) - Traffic type ID
description (String) - Traffic type description
unit (String) - Traffic type unit of measure
traffic_limit Collection
(traffic_limit)		 Collection of traffic limits associated (nested) to a service

Here is the description of a (nested) Traffic limit object:

Name Type Description
id Integer Unique ID of this traffic limit
volume Integer Volume limit of this traffic limit object
period Object id (Integer) - limit period ID
time_units (Integer) - number of units
unit (String) - Unit of measure

Service Profile 

Service Profile collection operations.

Retrieve Service Profile List
/api/v1/service_profile

Retrieves a collection of all Service Profiles for your organisation.

Returned service profiles contain just the total count of associated services, so this is the short view.

  • Response  200
  • Headers
    Content-Type: application/json
    X-Total-Count: 42
    Body
    [
  {
    "id": 232,
    "name": "Smart meter",
    "description": "Data + SMS - 1G limit",
    "used_count": "2",
    "allowed_3g": true,
    "allowed_4g": false
  },
  {
    "id": 2,
    "name": "Arduino",
    "description": "Data - unlimited",
    "used_count": "7",
    "allowed_3g": true,
    "allowed_4g": true
  }
]
Create a Service Profile
/api/v1/service_profile

Creates a new Service Profile.

Editable fields:

  • name (String required)

  • description (String optional)

  • allowed_3g (boolean optional, defaults to true)

  • allowed_4g (boolean optional, defaults to true)

  • api_callback (object optional)

  • api_secret (object optional)

  • moc_callback (object optional)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "Smart meter",
  "description": "Data + SMS - 1G limit",
  "allowed_3g": true,
  "allowed_4g": false,
  "api_callback": {
    "id": 1
  },
  "api_secret": {
    "id": 2
  },
  "moc_callback": {
    "id": 2
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/service_profile/232

Service Profile Operations 

Retrieve a Single Service Profile
/api/v1/service_profile/{profile_id}

Retrieve a service profile with a given id.

  • Parameters
  • profile_id
    number (required) 

    Service profile ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 232,
  "name": "Smart meter",
  "description": "Data + SMS - 1G limit",
  "allowed_3g": true,
  "allowed_4g": true,
  "used_count": 12,
  "api_callback": {
    "id": 38,
    "url": "https://www.customers-server.com",
    "created": "2015-03-18 16:11:07",
    "purpose": "Customer's Webserver"
  },
  "api_secret": {
    "id": 38,
    "purpose": "K3"
  },
  "moc_callback": {
    "id": 39,
    "url": "https://moc.customers-server.com",
    "created": "2015-03-18 16:11:17",
    "purpose": "Customer's Moc server"
  },
  "service": [
    {
      "id": 123,
      "description": "Data",
      "teleservice_code": 7678345,
      "traffic_type": {
        "id": 1,
        "description": "Data",
        "unit": "GB"
      },
      "traffic_limit": [
        {
          "id": 123,
          "volume": 64,
          "period": {
            "id": 33,
            "time_units": 5,
            "unit": "Days"
          }
        },
        {
          "id": 234,
          "volume": 128,
          "period": {
            "id": 35,
            "time_units": 1,
            "unit": "Months"
          }
        }
      ]
    }
  ]
}
Delete Service Profile
/api/v1/service_profile/{profile_id}

Deletes a service profile and all its associations with services and traffic limits. A service profile can only be deleted, if it is not selected on an endpoint. If it is not selected on an endpoint, the used_count is 0.

  • Parameters
  • profile_id
    number (required) 

    Service profile ID

  • Response  204
  • Response  409
  • Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Service Profile still referenced by Endpoint."
}
Update Service Profile
/api/v1/service_profile/{profile_id}

Update a service profile with a given id. Updates only proper attributes of service profile (name and description).

Service and traffic limit collections are managed via dedicated collection commands (see below).

Editable fields:

  • name (String optional)

  • description (String optional)

  • allowed_3g (boolean optional)

  • allowed_4g (boolean optional)

  • api_callback (object optional) can be emptied by setting the id to null (“api_callback”:{“id”:null})

  • api_secret (object optional) can be emptied by setting the id to null (“api_secret”:{“id”:null})

  • moc_callback (object optional) can be emptied by setting the id to null (“moc_callback”:{“id”:null})

  • Parameters
  • profile_id
    number (required) 

    Service profile ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "name": "Smart Probe",
  "description": "new description",
  "allowed_3g": false,
  "allowed_4g": false,
  "api_callback": {
    "id": 1
  },
  "api_secret": {
    "id": 1
  },
  "moc_callback": {
    "id": 3
  }
}
  • Response  204

Services in a Service Profile 

Associate a Service to a Profile
/api/v1/service_profile/{profile}/service/{service}

Add service to the collection of services associated to a profile. Multiple services can be assigned, but each only once.

  • Response  204
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "Service Profile - Service already exists."
}
Remove a Service From a Profile
/api/v1/service_profile/{profile}/service/{service}

Remove service from the collection of services associated to a profile. A service can only be removed if it has no assigned traffic limits.

  • Response  204
  • Response  409
  • Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Traffic Limit still referenced by Service."
}

Traffic Limit of a Service associated to a Service Profile 

Remove a Limit of a Service
/api/v1/service_profile/{profile}/service/{service}/traffic_limit/{traffic_limit}

Removes the assignment of a limit to a service associated to a profile service.

  • Parameters
  • profile
    number (required) 

    Service profile ID

    service
    number (required) 

    Service ID

    traffic_limit
    number (required) 

    traffic limit ID

  • Response  204
Add a Traffic Limit to a Service
/api/v1/service_profile/{profile}/service/{service}/traffic_limit/{traffic_limit}

Add traffic limit to a collection of traffic limits associated to a profile service.

  • Parameters
  • profile
    number (required) 

    Service profile ID

    service
    number (required) 

    Service ID

    traffic_limit
    number (required) 

    traffic limit ID

  • Response  204
  • Response  404

Service Lookups and Configuration 

This section describes calls used to manage service and traffic limit configuration. Traffic limits are configurable by user and associated to a service, while service and limit period are provided and NOT configurable by user.

Retrieve Available Services 

Retrieve Available Services
/api/v1/service

This API call retrieves a collection of available services. Services are read only objects.

Service objects contain expanded traffic limit nested objects.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 232,
    "description": "Data",
    "teleservice_code": 767,
    "used_with_vlr": true,
    "used_with_sgsn": true,
    "traffic_type": {
      "id": 1,
      "description": "Data",
      "unit": "MB"
    }
  },
  {
    "id": 123,
    "description": "SMS MO",
    "teleservice_code": 223,
    "used_with_vlr": true,
    "used_with_sgsn": true,
    "traffic_type": {
      "id": 2,
      "description": "SMS",
      "unit": "count"
    }
  },
  {
    "id": 212,
    "description": "SMS MT",
    "teleservice_code": 224,
    "used_with_vlr": true,
    "used_with_sgsn": true,
    "traffic_type": {
      "id": 2,
      "description": "SMS",
      "unit": "count"
    }
  }
]

Retrieve Service By ID 

Retrieve Service By ID
/api/v1/service/{id}

Retrieve a service identified by a given ID.

  • Parameters
  • id
    number (required) 

    Service ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 232,
  "description": "Data",
  "teleservice_code": 767,
  "used_with_vlr": true,
  "used_with_sgsn": true,
  "traffic_type": {
    "id": 1,
    "description": "Data",
    "unit": "GB"
  }
}

Traffic Limits Associated to a Service 

Retrieve Traffic Limits of a Services
/api/v1/service/{id}/traffic_limit

Traffic limits are system configuration parameters defined for a single service. Traffic limits do not have direct effect, but have to be explicitly assigned to an endpoint or a service profile.

  • Parameters
  • id
    number (required) 

    Service ID

  • Response  200
  • Body
    [
  {
    "id": 111,
    "volume": 64,
    "period": {
      "id": 33,
      "time_units": 5,
      "unit": "Days"
    }
  },
  {
    "id": 234,
    "volume": 128,
    "period": {
      "id": 35,
      "time_units": 1,
      "unit": "Months"
    }
  }
]
Create a New Traffic Limit Associated to a Service
/api/v1/service/{id}/traffic_limit

Not implemented.

Available fields:

  • Volume limit (Integer required)

  • Limit period (Object required)

  • Parameters
  • id
    number (required) 

    Service ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "volume": 64,
  "period": {
    "id": 21
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/service/11/traffic_limit/123

Retrieve all available Traffic Limits 

Not implemented.

Retrieve available Traffic Limits
/api/v1/traffic_limit
  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 111,
    "service": {
      "id": 123,
      "description": "data"
    },
    "volume": 64,
    "period": {
      "id": 33,
      "time_units": 5,
      "unit": "Days"
    }
  },
  {
    "id": 234,
    "service": {
      "id": 123,
      "description": "data"
    },
    "volume": 128,
    "period": {
      "id": 35,
      "time_units": 1,
      "unit": "Months"
    }
  }
]
Create Traffic Limit
/api/v1/traffic_limit

Not implemented.

Creates a traffic limit. Traffic limit has to be associated to a service.

Available fields:

  • Service (Object required)

  • Volume limit (Integer required)

  • Limit period (Object required)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "service": [
    {
      "id": 123
    }
  ],
  "volume": 64,
  "period": {
    "id": 21
  }
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/traffic_limit/123

Manage Traffic Limits 

Not implemented.

Retrieve a Traffic Limit
/api/v1/traffic_limit/{id}
  • Parameters
  • id
    number (required) 

    Service ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 111,
  "service": {
    "id": 123,
    "description": "data"
  },
  "volume": 64,
  "period": {
    "id": 33,
    "time_units": 5,
    "unit": "Days"
  }
}
Delete a Traffic Limit
/api/v1/traffic_limit/{id}
  • Parameters
  • id
    number (required) 

    Service ID

  • Response  204
Update a Traffic Limit
/api/v1/traffic_limit/{id}

Updates a single traffic limit object.

Update-able fields:

  • Service

  • Volume limit

  • Limit period

  • Parameters
  • id
    number (required) 

    Service ID

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "service": {
    "id": 123
  },
  "volume": 64,
  "period": {
    "id": 21
  }
}
  • Response  204

Retrieve Limit Periods 

Retrieve available Limit Periods
/api/v1/traffic_limit/period

Not implemented.

Limit periods are read only, lookup values used to define traffic limits.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 33,
    "time_units": 5,
    "unit": "Days"
  },
  {
    "id": 35,
    "time_units": 1,
    "unit": "Months"
  }
]

User Management 

EMnify system is a multi-tenancy system where tenant is an organisation.

Each organisation can have multiple users. The users of an organisation are managed by the administrator of this organisation or (possibly) the parent organisation.

  • When an organisation administrator manages own user space, setting explicitly an organisation for a user is optional. Then the organisation for the new account is inherited from the administrator user creating the account.
  • The organisation administrator may specify explicitly an organisation for a user, if the new user is to be created in a “child” (direct, not “grandchild”) organisation of this organisation.
  • The system-wide administrators (EMnify) must always specify an organisation when creating a user account.

Below is a sample user in JSON representation.

{
  "id": 123,
  "username": "eabbot@flatland.org",
  "name": "Edwin Abbott",
  "created": "2014-09-27T08:03:00+0000",
  "status": {
    "id": 1,
    "description": "Active"
  },
  "organisation": {
    "id": 123,
    "name": "Company"
  },
  "roles": [
    {
      "id": 2,
      "name": "User"
    },
    {
      "id": 3,
      "name": "Observer"
    }
  ]
}
Name Type Description
id Integer Unique ID of this user
username String username - used for login, for full functionality is has to be a valid email address
name String User`s full name
created Timestamp Timestamp when this user was created - Type: ISO 8601 timestamp format
status Object id (Integer) - ID of status of this user
description (String) - Description of meaning of the status
organisation Object id (Integer) - ID of organisation
name (String) - Name of the organisation
roles List of Objects List of one or more roles
mfa List of Objects List of one or more MFA keys, if any have been created by this user

User Collection & Creation 

List users
/api/v1/user?{q}{page}{per_page}{sort}

Retrieves the collection of user accounts registered within your organisation or the organisation`s immediate child organisations, filtered, sorted and paged accourding to query parameters.

  • Parameters
  • q
    String (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields,
    id,
    status,
    name,
    username,
    organisation.

    Example q=status:0,organisation:74

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields,
    id,
    status,
    name,
    username,
    organisation,
    created.

    Example sort=-status,id
    Sort by status descending and id ascending

  • Response  200
  • Headers
    Content-Type: application/json
    Link: <https://cdn.emnify.net/api/v1/user?q=status:0,organisation:74&per_page=100&sort=-status,id>; rel="first", <https://cdn.emnify.net/api/v1/user?q=status:0,organisation:74&page=5&per_page=100&sort=-status,id>; rel="prev", <https://cdn.emnify.net/api/v1/user?q=status:0,organisation:74&page=7&per_page=100&sort=-status,id>; rel="next", <https://cdn.emnify.net/api/v1/user?q=status:0,organisation:74&page=34&per_page=100&sort=-status,id>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: status:0,organisation:74
    X-Sort: -status,id
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "id": 42,
    "username": "ford.prefect@hitchhikerguide.net",
    "name": "Douglas Adams",
    "created": "1979-10-12T08:00:00+0000",
    "status": {
      "id": 2,
      "description": "Suspended"
    },
    "organisation": {
      "id": 42,
      "name": "Pan Books"
    },
    "mfa": [
      {
        "id": 12,
        "type": {
          "id": 0,
          "name": "Time-Based One-Time Password"
        },
        "status": {
          "id": 1,
          "name": "Active"
        },
        "creation_date": "2017-02-03T15:04:03+0100",
        "activation_date": "2017-02-04T10:14:13+0100"
      }
    ]
  },
  {
    "id": 123,
    "username": "eabbot@flatland.org",
    "name": "Edwin Abbott",
    "created": "2014-08-31T16:47:00+0000",
    "status": {
      "id": 1,
      "description": "Active"
    },
    "organisation": {
      "id": 123,
      "name": "Company"
    }
  }
]
Create User
/api/v1/user?{q}{page}{per_page}{sort}

User is created, but is not active and has no password assigned. The URL to get the user details is provided as Location Header in the response.

ACTIVATION

Upon creation, the user account undergoes an activation process (see services below ) in which she receives an email with activation link. Following this link the user is asked to set the password and upon successful completion of this process, the account becomes active and operational.

Provided fields:

  • Username (String required) - has to be the email of this user

  • Name (String required)

  • Organisation (Object optional) - may be provided by regular user, but is required for master user.

  • Roles (List of Objects optional) - List of one or more role Ids to be assigned at once. If missing, a default role is assigned

Notes

  • Password is not provided. Separate calls provide password management.

  • When the organisation of the new user is not specified in the request, it is inherited from the user creating the account. A regular user is allowed to specify only organisations which are direct children of his/her own organisation, or his/her own organisation.

  • The status field is not user editable at account creation time - the default imposed by server is ACTIVATION_PENDING.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "username": "eabbot@flatland.org",
  "name": "Edwin Abbott",
  "organisation": {
    "id": 123
  },
  "roles": [
    {
      "id": 1
    },
    {
      "id": 2
    }
  ]
}
  • Response  201
  • Headers
    Location: https://cdn.emnify.net/api/v1/user/42
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Role with Id '1111' not found."
}
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "Create User validation error",
  "errors": [
    {
      "error_code": 1401,
      "error_token": "InvalidReference",
      "message": "Organisation with id '10' not found."
    }
  ]
}

Single User Operations 

Retrieve the User
/api/v1/user/{id}

Get a specific user by id, provided the user is within this requesting users organisation or the organisations immediate child organisations.

  • Parameters
  • id
    number (required) 

    User ID (N.B. NOT username)

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 123,
  "username": "eabbot@flatland.org",
  "name": "Edwin Abbott",
  "created": "2014-08-31T16:47:00+0000",
  "status": {
    "id": 1,
    "description": "Active"
  },
  "organisation": {
    "id": 123,
    "name": "Company"
  },
  "roles": [
    {
      "id": 2,
      "name": "User"
    },
    {
      "id": 3,
      "name": "Observer"
    }
  ],
  "mfa": [
    {
      "id": 12,
      "type": {
        "id": 0,
        "name": "Time-Based One-Time Password"
      },
      "status": {
        "id": 1,
        "name": "Active"
      },
      "creation_date": "2017-02-03T15:04:03+0100",
      "activation_date": "2017-02-04T10:14:13+0100"
    }
  ]
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "User with id '13' not found"
}
Delete a user
/api/v1/user/{id}

Notes

  • A user can be deleted, if belonging to the same organisation as the requesting user, or to an organisation which is a direct child of the requesting user`s organisation.
  • Parameters
  • id
    number (required) 

    User ID (N.B. NOT username)

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "User with id '13' not found"
}
Update User
/api/v1/user/{id}

Provided fields

  • Username (String optional) - has to be user`s email

  • Name (String optional)

  • Status (Object optional)

  • Organisation (Object optional) - must be the current organisation or not to be provided

Notes

  • Password is not provided. Separate calls provide password management.

  • The organisation is not modifiable. A user can be updated, if belonging to the same organisation as the requesting user, or to an organisation which is a direct child of the requesting user`s organisation.

  • Status can be changed between ACTIVE (id: 1) and SUSPENDED (id: 2), and from ACTIVATION_PENDING (id: 0) to SUSPENDED.

Modifying the username invalidates account and triggers the activation procedure.

  • Parameters
  • id
    number (required) 

    User ID (N.B. NOT username)

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "username": "eabbot@flatland.org",
  "name": "Edwin Abbott",
  "status": {
    "id": 1
  }
}
  • Response  204
  • Response  422
  • Body
    {
  "error_code": 1400,
  "error_token": "InputValidationFailed",
  "message": "Request validation failed",
  "errors": [
    {
      "error_code": 1406,
      "error_token": "NotAllowed",
      "message": "User status 'ACTIVE' not allowed."
    }
  ]
}

Retrieve User By Username 

Retrieve User By Username
/api/v1/user/{username}

Get a specific user by username, provided the user is within this requesting users organisation or the organisations immediate child organisations.

  • Parameters
  • username
    String (required) 

    username

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    {
  "id": 123,
  "username": "eabbot@flatland.org",
  "name": "Edwin Abbott",
  "created": "2014-08-31T16:47:00+00:00",
  "status": {
    "id": 1,
    "description": "Active"
  },
  "organisation": {
    "id": 123,
    "name": "Company"
  }
}
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "User with username 'unaccessible_user' not found."
}

Retrieve Available User Statuses 

Retrieve Available User Statuses
/api/v1/user/status

Provides the list of available user status (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "description": "Activation Pending"
  },
  {
    "id": 1,
    "description": "Active"
  },
  {
    "id": 2,
    "description": "Suspended"
  },
  {
    "id": 3,
    "description": "Deleted"
  }
]

Role Collection 

List Roles
/api/v1/user/role

Retrieves the collection of available user roles

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
    {
      "id": 1, 
      "name": "Administrator"
    },
    {
      "id": 2, 
      "name": "User"
    },
    {
      "id": 3, 
      "name": "Observer"
    },
    ...
]

User Role Permissions 

List User Role Permissions
/api/v1/user/{id}/role/permission

Role permissions available to this user. Only an administrator or observer is allowed to see the role permissions of other users, provided they belong to an organisation he/she has access to.

Any user can also retrieve one’s own role permissions at
/api/v1/user/my/role/permission.

  • Parameters
  • id
    number (required) 

    User ID

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
    {
      "role": "User",
      "permissions": [
        {
            "method": "GET",
            "uri": "/api/v1",
            "description": "List of available API Entrypoints"
        },
        {
            "method": "GET",
            "uri": "/api/v1/endpoint/status",
            "description": "List of available Endpoint Statuses"
        },
        ...
      ]
    }, 
    {
      "role": "Observer",
      "permissions": [
        {
            "method": "GET",
            "uri": "/api/v1",
            "description": "List of available API Entrypoints"
        },
        {
            "method": "GET",
            "uri": "/api/v1/endpoint/status",
            "description": "List of available Endpoint Statuses"
        },
        ...
      ]
    }
]

Managing User Roles 

API access for a user is limited by his assigned role(s). Every role comes with a set of permissions, therefore a user is allowed to perform a specific action (GET, POST etc.) on a given entrypoint, only if the corresponding permission is included in one of his roles.

Assign Role to User
/api/v1/user/{id}/role/{roleId}

Role is assigned to this user.

  • Parameters
  • id
    number (required) 

    User ID

    roleId
    number (required) 

    Role ID to be assigned

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "Role with Id '7' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "Cannot assign the same role multiple times: Role 3"
}
Remove a Role from User
/api/v1/user/{id}/role/{roleId}

Release a Role from association with this user. Note that a Role can only be removed, if it is not the last role of this user.

  • Parameters
  • id
    number (required) 

    User ID

    roleId
    number (required) 

    Role ID to be removed

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "User with Id '12345' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "Cannot delete the last Role of the User."
}

Events of a User 

Retrieve Events
/api/v1/user/{user_id}/event?{q}{page}{per_page}{sort}

Returns the list of events, filtered, sorted and paged according to query parameters.
Only an administrator or observer may be allowed to see events of other users, provided they belong to an organisation he/she has access to.
Any user can also retrieve one’s own events at
/api/v1/user/my/event?{q}{page}{per_page}{sort}

  • Parameters
  • q
    number (optional) 

    Filter parameter in : format. Expects comma separated list out of the allowed fields, i.e. timestamp, description, source, severity, organisation, endpoint, tags, ip_address, imei, iccid, imsi. Example q=source:2,tags:Monitoring

    page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields, i.e. timestamp, id.
    Example sort=-timestamp,id
    Sort by timestamp descending and id ascending

  • Response  200
  • Headers
    Link: <https://cdn.emnify.net/api/v1/user/1/event?q=source:2&per_page=100&sort=-severity,timestamp>; rel="first", <https://cdn.emnify.net/api/v1/user/1/event?q=source:2&page=5&per_page=100&sort=-severity,timestamp>; rel="prev", <https://cdn.emnify.net/api/v1/user/1/event?q=source:2&page=7&per_page=100&sort=-severity,timestamp>; rel="next", <https://cdn.emnify.net/api/v1/user/1/event?q=source:2&page=34&per_page=100&sort=-severity,timestamp>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 3
    X-Filter: source:2
    X-Sort: -severity,timestamp
    X-Total-Count: 350
    X-Total-Pages: 4
    Body
    [
  {
    "id": 11,
    "alert": false,
    "description": " Failed authentication request from 'ford.prefect@hitchhikerguide.net', Reason: invalid passwort from IP 1.2.3.4",
    "timestamp": "2017-05-08T10:56:25.000+0000",
    "event_type": {
      "id": 6,
      "description": "User authentication failed"
    },
    "event_source": {
      "id": 2,
      "description": "API"
    },
    "event_severity": {
      "id": 1,
      "description": "Warn"
    },
    "organisation": {
      "id": 123,
      "name": "Seeley & Co."
    },
    "user": {
      "id": 42,
      "username": "ford.prefect@hitchhikerguide.net",
      "name": "Ford Prefect"
    }
  },
  {
    "id": 12,
    "alert": false,
    "description": "MFA key with Id '1' of Type 'Time-Based One-Time Password' deleted for user 'eabbot@flatland.org'",
    "timestamp": "2017-05-08T11:04:34.000+0000",
    "event_type": {
      "id": 14,
      "description": "Multi-factor Authentication"
    },
    "event_source": {
      "id": 2,
      "description": "API"
    },
    "event_severity": {
      "id": 0,
      "description": "Info"
    },
    "organisation": {
      "id": 123,
      "name": "Seeley & Co."
    },
    "user": {
      "id": 123,
      "username": "eabbot@flatland.org",
      "name": "Edwin Abbott"
    }
  }
]

Password Management and Activation 

Creating a user account sets this account to status ACTIVATION_PENDING, which requires activation by the (newly created) user. The user is sent an activation link via email. In order to activate the account, the user has to follow the link and define her/his password.

Account Activation 

Account Activation
/api/v1/user/activation

This service activates the account and sets the password. The activation key is sent via email.

User has to provide:

  • Activation token (String required) - the activation token was sent to a user via email

  • Password (String required)

  • This is a public (unauthenticated) service which ignores authentication token
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "activationKey": "28fcfd949ee1bb79e7892b9",
  "password": "2fd4e1c87a2d20fced849ee7bb76e7391b93ee12"
}
  • Response  204
  • Response  400

Re-send Activation Mail 

Re-send Activation Mail
/api/v1/user/activation_resend

This service re-sends activation mail to the user. As this endpoint is open to the public (no authentication token necessary), it requires instead the google reCAPTCHA token to ensure that no robot is performing the request. Moreover there is a time limit on how often a given user may be issued with a new Activation Mail.

User has to provide:

  • username (String required)

  • g-recaptcha-response (String required) - auto-generated from a form using Google reCAPTCHA

Notes

According to the reCAPTCHA documentation

https://developers.google.com/recaptcha/docs/display

a “Site Key” is necessary.

If you want to implement this feature in your client, please contact EMnify support to obtain this “Site Key” for your domain.

  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "username": "user@domain.com",
  "g-recaptcha-response": "03AHJ_VutFSI0qC6ycL3 ..."
}
  • Response  204

Change Password 

Change Password
/api/v1/user/password

Password change service. Allows to change the password for the currently authenticated user.

User has to provide:

  • Old password (String required)

  • New password (String required)

Notes

  • Client application should invalidate the authentication token.
  • Request
  • Headers
    Content-Type: application/json
    Body
    {
  "old_password": "myoldpassword",
  "new_password": "mynewpassword"
}
  • Response  204
  • Response  422
  • Headers
    Content-Type: application/json
    Body
    {
  "error_code": 1002,
  "error_token": "Failed",
  "message": "Invalid old password",
  "errors": [
    {
      "error_code": 1400,
      "error_token": "InputValidationFailed",
      "message": "Wrong Password for User 'own_username'"
    }
  ]
}

IP Address Spaces 

Retrieve IP Address Spaces 

Sample IP address space:

[
  {
    "id": 1,
    "ip_address_space": "10.199.128.0/18",
    "ip_address_version": 4,
    "used_count": 2,
    "available_count": 16380
  }
]

Description of IP address space properties:

Name Type Description
id Integer Unique ID of this address space
ip_address_space String subnet of the IP address space
ip_address_version Integer IP version for this address space, e.g. 4 or 6
used_count Integer count of endpoints, who belong to this address space
available_count Integer count of available (not used) IP addresses in this address space’s subnet
Retrieve own IP Address Spaces
/api/v1/ip_address_space

Returns the list of IP address space for the requesting user’s organisation

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "ip_address_space": "10.199.128.0/18",
    "ip_address_version": 4,
    "used_count": 2,
    "available_count": 16380
  },
  {
    "id": 2,
    "ip_address_space": "10.199.192.0/18",
    "ip_address_version": 4,
    "used_count": 2,
    "available_count": 16380
  }
]

Retrieve Available IP Address Spaces 

Retrieve Available Address Spaces
/api/v1/ip_address_space/available?{ip_address_version}

Provides a list of 10 random available address spaces (unassigned to any organisation). As the list is generated for each request, two successive requests will have different results.

  • Parameters
  • ip_address_version
    number (optional) 

    filter by IPv4 which is default or by IPv6. Example: ip_address_version=4 or ip_address_version=6

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "ip_address_space": "10.199.128.0/18",
    "ip_address_version": 4
  },
  {
    "id": 2,
    "ip_address_space": "10.199.192.0/18",
    "ip_address_version": 4
  }
]

Managing IP Address Spaces 

Assign IP Address Space
/api/v1/ip_address_space/{id}

Available IP address space is assigned to the user’s organisation.

  • Parameters
  • id
    number (required) 

    ID of the IP address space to be assigned

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "IP Address Space with Id '27' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1405,
  "error_token": "Duplicated",
  "message": "IP Address Space with Id '27' already assigned."
}
Remove an Associated IP Address Space
/api/v1/ip_address_space/{id}

Release the IP address space from association with the user’s organisation. Note that IP address spaces can only be removed, if the IP address space is not used on any of the organisations endpoints.

  • Parameters
  • id
    number (required) 

    ID of the IP address space to be removed

  • Response  204
  • Response  404
  • Body
    {
  "error_code": 1401,
  "error_token": "InvalidReference",
  "message": "IP Address Space with Id '27' not found."
}
  • Response  409
  • Body
    {
  "error_code": 1407,
  "error_token": "CannotBeDeleted",
  "message": "IP Address Space still referenced by endpoints."
}

Events 

Retrieve Events 

Sample Event:

[
  {
    "timestamp": "2015-07-16 12:07:09",
    "alert": true,
    "description": "PDP Context deleted.",
    "id": 69535,
    "event_type":{
      "description": "Delete PDP Context",
      "id": 4
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 69
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 110
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    }
  }
]

Description of event properties:

Name Type Description
id Integer Unique ID of this event
timestamp Date Date when the event happened
description String Description of the event
event_type Object Type of the event
event_source Object Source of the event, for example network or API
event_severity Object Severity of the event, can be Info, Warn, Critical
alert Boolean if true, shows up as alert in EUI
organisation Object Organisation (id and name) of the event
user Object User (id, username and name) of the event
endpoint Object affected endpoint (includes id, name, tags, ip address and imei)
sim Object affected SIM (includes id, iccid and production date)
imsi Object affected IMSI (includes id, imsi and import date)
detail Object optional additional information
Retrieve Events
/api/v1/event?{q}{page}{per_page}{sort}

Returns the list of events, filtered, sorted and paged according to query parameters.

  • Parameters
  • page
    number (optional) 

    Paging parameters - current page

    per_page
    number (optional) 

    Paging parameters - number of items per page

    sort
    String (optional) 

    Sort properties according to comma separated list out of the allowed fields, e.g. timestamp, id.
    Example sort=-timestamp,id
    Sort by timestamp descending and id ascending

    q
    number (optional) 

    Filter parameter in : format. Expects comma separated list out of allowed fields.

    filter name possible values example
    id event id id:1123
    type event_type id type:1
    source 0, 1, 2 source:1
    severity 0, 1, 2 severity:2
    alert true, false alert:true
    description event description String partial match description:deactivated
    organisation organisation name String partial match organisation:Enterprise2
    user username String partial match user:eabbot
    endpoint endpoint name String partial match endpoint:Endpoint2
    tags endpoint tags String partial match tags:arduino
    ip_address endpoint IP address String partial match ip_address:10.1.1
    iccid sim iccid String exact match iccid:1234567890123456789
    imsi imsi digits String exact match imsi:112201234567890
    timestamp event timestamp matching a single day timestamp:2015-02-03
  • Response  200
  • Headers
    Link: <https://cdn.emnify.net/api/v1/event?q=source:2,alert:false&per_page=100&sort=-severity,timestamp>; rel="first", <https://cdn.emnify.net/api/v1/event?q=source:2,alert:false&page=5&per_page=100&sort=-severity,timestamp>; rel="prev", <https://cdn.emnify.net/api/v1/event?q=source:2,alert:false&page=7&per_page=100&sort=-severity,timestamp>; rel="next", <https://cdn.emnify.net/api/v1/event?q=source:2,alert:false&page=34&per_page=100&sort=-severity,timestamp>; rel="last"
    X-Count-Per-Page: 100
    X-Current-Page: 6
    X-Filter: source:2,alert:false
    X-Sort: -severity,timestamp
    X-Total-Count: 3350
    X-Total-Pages: 34
    Body
    [
  {
    "id": 14,
    "alert": false,
    "description": "MFA key with Id '1' of Type 'Time-Based One-Time Password' deleted for user 'root@localhost'",
    "timestamp": "2017-05-05T12:00:30.000+0000",
    "event_type": {
      "id": 14,
      "description": "Multi-factor Authentication"
    },
    "event_source": {
      "id": 2,
      "description": "API"
    },
    "event_severity": {
      "id": 0,
      "description": "Info"
    },
    "organisation": {
      "id": 4,
      "name": "MNO 1"
    },
    "user": {
      "id": 2,
      "username": "eabbot@flatland.org",
      "name": "Edwin Abbot"
    }
  },
  {
    "timestamp": "2015-07-16 12:08:26",
    "alert": false,
    "description": "New location received from SGSN for IMSI='901430000000114', now attached to SGSN='49175.telekom.mcc262.mnc01.t-mobile.de', IP='0.0.0.0'.",
    "id": 69536,
    "event_type": {
      "description": "Update GPRS location",
      "id": 2
    },
    "event_source": {
      "name": "Network",
      "id": 0
    },
    "event_severity": {
      "description": "INFO",
      "id": 0
    },
    "organisation": {
      "name": "Organisation_Name",
      "id": 2
    },
    "endpoint": {
      "name": "Monitoring201",
      "tags": "Monitoring",
      "ip_address": "10.199.6.39",
      "imei": null,
      "id": 69
    },
    "sim": {
      "iccid": "8988317000000000100",
      "production_date": "2014-12-17 13:26:13",
      "id": 110
    },
    "imsi": {
      "imsi": "901430000000114",
      "import_date": "2014-12-17 13:26:08",
      "id": 110
    },
    "detail": {
      "id": 2,
      "name": "Telekom",
      "country": {
        "id": 74,
        "name": "Germany",
        "country_code": "49",
        "mcc": "262",
        "iso_code": "de"
      },
      "tapcode": [
        {
          "id": 1,
          "tapcode": "DEUD1"
        }
      ],
      "mnc": [
        {
          "id": 2,
          "mnc": "01"
        }
      ]
    }
  }
]

Retrieve Event Types 

Retrieve Event Types
/api/v1/event/type

Provides the list of event_types (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 0,
    "description": "Generic"
  },
  {
    "id": 1,
    "description": "Update Location"
  },
  {
    "id": 2,
    "description": "Update GPRS Location"
  },
  {
    "id": 3,
    "description": "Create PDP Context"
  },
  {
    "id": 4,
    "description": "Update PDP Context"
  },
  {
    "id": 5,
    "description": "Delete PDP Context"
  },
  {
    "id": 6,
    "description": "User authentication failed"
  },
  {
    "id": 7,
    "description": "Application authentication failed"
  },
  {
    "id": 8,
    "description": "SIM activation"
  },
  {
    "id": 9,
    "description": "SIM suspension"
  },
  {
    "id": 10,
    "description": "SIM deletion"
  }
]

Lookups 

Retrieve Available Countries 

Retrieve Available Countries
/api/v1/country

Provides the list of available countries (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "name": "Germany",
    "country_code": "49",
    "mcc": "262",
    "iso_code": "de"
  },
  {
    "id": 2,
    "name": "Italy",
    "country_code": "39",
    "mcc": "222",
    "iso_code": "it"
  }
]

Retrieve Available Currencies 

Retrieve Available Currencies
/api/v1/currency

Provides the list of available currencies (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "code": "EUR",
    "symbol": "€"
  },
  {
    "id": 2,
    "code": "USD",
    "symbol": "$"
  }
]

Retrieve Available Data Blocksizes 

Retrieve Available Data Blocksizes
/api/v1/data_blocksize

Provides the list of available data blocksizes (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "octets": "1",
    "description": "exact"
  },
  {
    "id": 2,
    "octets": "8",
    "description": "fuzzy"
  }
]

Retrieve Available Data Throttles 

Retrieve Available Data Throttles
/api/v1/data_throttle

Provides the list of available data throttles (lookup).

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 1,
    "octets": "128000",
    "description": "128 kbit/s"
  },
  {
    "id": 2,
    "octets": "256000",
    "description": "256 kbit/s"
  }
]

Retrieve Available Operators 

Retrieve Available Operators
/api/v1/operator

Provides the list of available operators.

  • Response  200
  • Headers
    Content-Type: application/json
    Body
    [
  {
    "id": 2,
    "name": "Telekom",
    "country": {
      "id": 74,
      "name": "Germany",
      "country_code": "49",
      "mcc": "262",
      "iso_code": "de"
    },
    "tapcode": [
      {
        "id": 1,
        "tapcode": "DEUD1"
      }
    ],
    "mnc": [
      {
        "id": 1,
        "mnc": "01"
      }
    ]
  },
  {
    "id": 5,
    "name": "O2",
    "country": {
      "id": 74,
      "name": "Germany",
      "country_code": "49",
      "mcc": "262",
      "iso_code": "de"
    },
    "tapcode": [
      {
        "id": 3,
        "tapcode": "DEUE2"
      },
      {
        "id": 4,
        "tapcode": "DEUO2"
      }
    ],
    "mnc": [
      {
        "id": 5,
        "mnc": "07"
      },
      {
        "id": 7,
        "mnc": "08"
      }
    ]
  }
]

Generated by aglio on 21 Mar 2018