Using Hologram's REST API - A guide for beginners

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 the 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 action and/or perform actions programmatically.

 Anatomy of an endpoint

api-structure.png

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

4) ?  - 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.

5) 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

6) &  - Used to separate API URL Parameters

7) 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}"
 }
 

8) 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"
}
 

 

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 globalglobalexclca, USA, usaall, 1, or 2.

Screen_Shot_2019-10-22_at_20.18.25.png

 

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}
Screen_Shot_2019-10-22_at_19.59.43.png

 

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}"}

 

Was this article helpful?
0 out of 0 found this helpful