Beginner's guide to the Hologram REST API

What is a REST API?

In the scope of Hologram the REST API is a set of web commands, also called endpoints, used to perform actions that are traditionally performed through your dashboard. This includes, among other things, SIM activations, account organization, messaging, and device and organization monitoring. The true power of the API comes when users want to take bulk actions and/or perform actions programmatically.

Anatomy of an endpoint

1) HTTP verbs - Used as a prefix to an endpoint and dictate the type of action, these are a standard part of all REST APIs.

 The HTTP verbs used in Hologram’s REST API are:

• GET – Used to get information. No changes are made.
• POST – Used to create a change. May require a body.
• PUT - Used to update an existing entry. May require a body.
• DELETE – Used to delete information.  May require a body.

2) API URL ID This is the part of an endpoint where you identify the REST API. For Hologram’s REST API the first part of the API URL will always be https://dashboard.hologram.io/api/1/

3) API URL Category - This indicates what category of information you will be dealing with. 

Examples of API URL Categories in Hologram's REST API are:

• plans – Cellular Plans
• links/cellular – SIMs
• devices – Devices
• csr/rdm – Cloud services
• sms – SMS services
• tunnelkeys – Spacebridge services
• usage – Data and SMS usage
• users – User
• organizations – Organizations

 ?  - A question mark separates the general API URL from the API URL parameters. It should only be used when an API endpoint is being used with parameters.

4) API URL Parameters – These add context to your API request.

Examples of Parameters are:

• apikey – Your API KEY
• orgid – Your organization’s ID
• limit – A limit to the amount of responses you want to get
• sim – Your SIM ID (ICCID)
• tagname – Name of a tag

5) &  - Used to separate API URL Parameters

6) Body – Used for certain endpoints. This is more information passed onto the call in JSON format.

An example of a formatted body is:

{ 
    "sims": [
        "{SIM_NUMBER_1}",
        "{SIM_NUMBER_2}",
        "{SIM_NUMBER_N}"
    ],
    "plan": {YOUR_PLAN_NUMBER},
    "zone": "{YOUR_PLAN'S_ZONE}"
 } 

7) Header - Used for authentication. This is passed onto the call in JSON format.

An example of a formatted header is:

{ 
    "Authorization":"Basic Base64EncodedUsernameandAPIKey"
}

 

REST API Security 

In order to use the REST API, you will need to either include your Hologram API KEY or use your username and password to authenticate.

You include your API Key in the header base64 encoded. To do this:

1. Grab your API Key from the Dashboard.
2. Copy and paste apikey:[YOUR_API_KEY] in this base64 encoder tool. Make sure you replace [YOUR_API_KEY] with the API Key you got from the Dashboard. Include the colon ":" but do not include the brackets "[]".

API endpoints covered in this guide:

• GET Plan information
• POST Activate SIMs
• GET Tags
• GET Device and Link ID
• POST Tag SIMs
• POST Change Plans
• POST Change Overage Limit
• POST Pause Device
• PUT Update Device Name

For more REST API endpoints, please visit our REST API Page.

Before we begin please note that, with the exception of encapsulating body information, any time something is between curly brackets you will need to replace it with information belonging to your account. 

For example if you see an endpoint that has: …orgid={YOUR_ORGID} when you use it, it should look like this: …orgid=1234

This is an example of a body:

{
"simrange":"{FIRST_SIM_IN_RANGE-LAST_SIM_IN_RANGE}",
"plan": {YOUR_PLAN_NUMBER},
"zone": "{YOUR_PLAN'S_ZONE}"
}

Becomes

{
"simrange":"1234-7890",
"plan": 1,
"zone":"global"
}

Furthermore, please note that endpoints that take arrays of data have a limit of 2,000 items.

 

Get Plan information

GET https://dashboard.hologram.io/api/1/plans?orgid={YOUR_ORGID}

This will return a list of all the plans you have access to. If you plan to use this information to activate SIMs you'll need the id field and the zones  field which should be either global, globalexclca, USA, usaall, 1, or 2.

 

Activate SIMs 

POST https://dashboard.hologram.io/api/1/links/cellular/bulkclaim?orgid={YOUR_ORGID}

 Here we have two options, send a list of SIM numbers or send a SIM range. SIM number lists are ideal for unordered SIMs while SIM ranges are ideal for users who have purchased SIMs in the 100 pack or 1000 pack option as well as spools of embedded SIMs. 

If you are planning on using a list of SIM numbers, your request should have the following body:

{
    "sims":["{SIM_NUMBER_1}","{SIM_NUMBER_2}","{SIM_NUMBER_N}"],
    "plan": {YOUR_PLAN_NUMBER},
    "zone":"{YOUR_PLAN'S_ZONE}"
}

If you are planning on using a SIM range, your request should have the following body:

{ "simrange": "{FIRST_SIM_IN_RANGE-LAST_SIM_IN_RANGE}", "plan": {YOUR_PLAN_NUMBER}, "zone": "{YOUR_PLAN'S_ZONE}"}

For more information on bulk activation check out our Bulk Activation Guide. 

 

Get Tags

GET https://dashboard.hologram.io/api/1/devices/tags?orgid={YOUR_ORGID}

 

Get Device ID and Link ID 

GET https://dashboard.hologram.io/api/1/devices?orgid={YOUR_ORGID}

 

POST Tag SIMs

POST https://dashboard.hologram.io/api/1/devices/tags/{TAGID}/link?orgid={YOUR_ORGID}

Body:

{"deviceids":[{YOUR_DEVICE_ID}]}

 

 

POST Change Plans

POST https://dashboard.hologram.io/api/1/links/cellular/changeplan?orgid={YOUR_ORGID}

Body:

{
    "linkids": [
        {linkid_1},
        {linkid_2},
        {linkid_N}
    ], 
    "plan": {Plan_Number}, 
    "tier": {tier}, 
    "orgid": {orgid}
}

 

POST Change Overage Limit

POST https://dashboard.hologram.io/api/1/links/cellular/{linkid}/overagelimit?orgid={YOUR_ORGID}

Body:

{"limit":{YOUR_LIMIT}}

 

POST Pause Device

POST https://dashboard.hologram.io/api/1/links/cellular/{linkid}/state?orgid={YOUR_ORGID}

Body:

{"state":"{POSSIBLE_STATE}"}

Possible states: pause or live  

 

PUT Update Device Name

PUT https://dashboard.hologram.io/api/1/devices/{DEVICEID}?orgid={YOUR_ORGID}

Body:

{"name":"{YOUR_DESIRED_DEVICE_NAME}"}