What is a REST API?

In the scope of Hologram the REST API is a set of web commands, also called endpoints, used to preform actions that are traditionally preformed 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 preform 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

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 Call.

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


REST API Security 

In order to use a rest API you will need to either pass your Hologram credentials or use your API KEY. In this guide we will always use the API Key. However, if you plan on using your credentials instead don’t forget to remove the apikey API URL parameter. Furthermore, if you only have one organization you can omit the orgid API URL parameter.

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, anytime 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?apikey={YOUR_API_KEY}&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 , USA, 1  , or 2 .

Activate SIMs 

POST https://dashboard.hologram.io/api/1/links/cellular/bulkclaim?apikey={YOUR_API_KEY}&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?apikey={YOUR_API_KEY}&orgid={YOUR_ORGID}

 

Get Device ID and Link ID 

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

 

POST Tag SIMs

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

Body: {"deviceids":[{YOUR_DEVICE_ID}]}

 

POST Change Plans

POST https://dashboard.hologram.io/api/1/links/cellular/changeplan?apikey={YOUR_API_KEY}&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?apikey={YOUR_API_KEY}&orgid={YOUR_ORGID} 

Body: {"limit":{YOUR_LIMIT}}

 

POST Pause Device

POST https://dashboard.hologram.io/api/1/links/cellular/{linkid}/state? apikey={YOUR_API_KEY}&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}?apikey={YOUR_API_KEY}&orgid={YOUR_ORGID} 

Body: {"name":"{YOUR_DESIRED_DEVICE_NAME}"}

 

Did this answer your question?