API

Documentation

API Functionality

General Information

1NCE offers an Application Programming Interface (hereinafter referred to as “API”) that allows users to implement the most important functions of the Customer Portal into a customer’s environment. The supported functions of the 1NCE API generally enables the customer to manage, control and monitor the 1NCE SIM Cards from an external system.

 

Customized API usage

The 1NCE API can be found under the following link:

https://api.1nce.com

To get the 1NCE API started the customer needs to authenticate himself. This can be done by clicking on the „Authorize“-button. The customer is asked to enter his credentials, which as an “Owner” typically are the same credentials as the one for the 1NCE Customer Portal (e-mail address and password). As an “API User” these credentials are the client ID, with the account number as a prefix, and the related client secret.

 

Afterwards, you can try the different requests of the 1NCE API, which are as follows:

1. /orders ->Order Controller

GET/v1/orders

Get a List of Orders

POST/v1/orders

Post an order

GET/v1/orders/{order_number}

Get a single Order, identified by its order number

2. /products ->Product information

GET/v1/products

Get a list of products

3. /sims ->Manage your SIMs

GET/v1/sims

Get a List of SIM Cards

POST/v1/sims

Change a list of SIM Cards for activate, deactivate, label, IMEI lock, etc.

GET/v1/sims/{iccid}

Get status information i.e. status, label, MSISDN, IMSI, ICCID, Lifetime, for a device with an ICCID

PUT/v1/sims/{iccid}

Modification of a SIM Card to activate, deactivate, change label, change IMEI lock, etc.

GET/v1/sims/{iccid}/connectivity_info

Retrieve connectivity information and location for a SIM

GET/v1/sims/{iccid}/events

Get diagnostic/event information for a SIM Card i.e. network events

GET/v1/sims/{iccid}/quota/data

Get the data quota of a SIM

GET/v1/sims/{iccid}/quota/sms

Get the SMS quota of a SIM

POST/v1/sims/{iccid}/reset

Trigger a connectivity reset for a given SIM Card. The actual reset will be done asynchronously. A positive-response only means that the connectivity-reset has been successfully placed into the queue.

GET/v1/sims/{iccid}/sms

Get the list of SMS sent and received by this SIM Card

POST/v1/sims/{iccid}/sms

Submit SMS to specific SIM Card

GET/v1/sims/{iccid}/sms/{id}

Get details about the SMS

DELETE/v1/sims/{iccid}/sms/{id}

Cancel SMS that is buffered for SIM Card and not yet delivered

POST/v1/sims/{iccid}/topup

Top up the data volume of a specific SIM Card

GET/v1/sims/{iccid}/usage

Get the daily usage generated by a SIM Card

POST/v1/sims/topup

Top up the data volume of specific SIM Cards

You get a detailed description of how to use each request by clicking on the specific request bar. To unfold an overview of the specific instructions and parameters you need to click on the button “Try it out”.

To unfold the function you want to use klick on the according bar in the list
As long as you are authorized you can hit the “Try it out”-button on the right to enter your own ICCID.
You then can start a test run by clicking on the button “Execute”.

Authentification

The usage of 1NCE REST API via the customer’s external system demands for an authentication first. Therefore, the authentication via OAuth2 with the same credentials being used as for the 1NCE Customer Portal (e-mail address and password) is required. As an “API User” the authentication method with client_id and client_secret is required.

The OAuth2 authentication is necessary to get a token with credentials of the 1NCE Customer Portal with the following workflow:

 

  • Send your credential base64 encoded to the authentication server.
  • Get a response including an UUID for authentication.
  • Use the UUID to authenticate REST requests.

 

The UUID for authentication has a validity period of 240 minutes. Notice: If the 240 minutes have expired the authentication process needs to be repeated. Send the authentication request via POST to

 

“`

https://api.1nce.com/management-api/oauth/token

“`

1. Request

**Header**

“`json

{

‘Content-Type’: ‘application/x-www-form-urlencoded’,

‘authorization’: ‘Basic <base64 encoded username:password>’

}

“`

**Body**

“`json

{

‘grant_type’: ‘client_credentials’

}

“`

2. Response

“`json

{

“access_token”:”6ba7b810-9dad-11d1-80b4-00c04fd43XXX”, // this is the

UUID token you want to use for authentication

“token_type”:”bearer”,

“expires_in”:3599,

“scope”:”all”,

“appToken”:”<application_token>”, // not relevant in this context

“userId”:<id>,

“orgId”:4321 // example

}

“`

 

Note: Only when you are authenticated you can send requests and receive the responses.

API doc

1NCE also offers a comfortable overview of all API requests in an API doc which you can access with link

 

https://api.1nce.com/management-api/api-docs

 

at the top of the page.

 


(This page might not be fully functional with every browser, prefered: Firefox 63.0 or higher)