Introduction & Authentication

Last updated: February 7th 2019

Introduction

About the Sensorpro API

The Sensorpro API is a RESTful JSON-based API. Its functionality is exposed through well-defined web URLs that follow standard conventions using an easy-to-read data format.

Values which need to be substituted into URLs will be denoted in square brackets.

Determine the Success or Failure of a Service Call

Each response contains a result object. The result object is used to determine if a request failed and to get any status messages which may be available for this request. The structure of the result object is shown below.

  • TotalErrors: Use this to determine if the request was successful. If this has a value > 0 the request failed.
  • ErrorMessages: This array contains the list of error messages for this request.
  • TotalStatusMessages: These are status messages which may be used for informational purposes and do not indicate an error.
  • StatusMessages: This array contains the list of status messages for this request.
  • Sequence: If this is a multi-operation service for example adding 10 records to the contact record. The stack of records being added will run from 0 to 9. If record 6 fails to add because the record already exists, the sequence number in the error collection would be 6.
  • Description: Description of error or status message.
  • Code: Status or error message code.

Example Response

"Result": {
	 "RequestId": "00000000-0000-0000-0000-000000000000",
	 "ErrorMessages": [],
	 "StatusMesssages": [],
	 "TotalStatusMessages": 0,
	 "TotalErrors": 0
 }

Authentication

SIGNIN

The authorisation API must be called to get an access token which is then used to authenticate subsequent API calls. The API is locked down by IP address you will need to contact support to get your IP address whitelisted. This should be the IP address of the machine where the API calls originate.

Authentication Endpoint
Method: POST
https://apinie.sensorpro.net/auth/sys/signin

Copy to Clipboard

Header Values
Header Example Description
Content-Type application/json;  
x-apikey 5F9B1BB2-1850-42A6-A6F7-7848B8D3708D Retrieved from API keys - Use menu "API" | "API keys" Select "Sensorpro rest API default key". Whitelist the calling ip address by editing the api key properties.

Request Body


    {
        "Organization": "YOURORGANIZATION",
        "User": "APIUSER",
        "Password":"PASSWORD"
    }
                                    

Input Parameters

    • Organization Your organization
    • User Your user, needs to be an API user. API users have no access to UI and normal users have no access to the API.
    • Password API user password
Response

    {
        "ExpiresIn": 3622,
        "APIEndpoint": "https://apinie.sensorpro.net/",
        "Token": "59701e8b-a6c4-43f0-a7a6-af05ccf8a60d",
        "Result": {
            "RequestId": "00000000-0000-0000-0000-000000000000",
            "ErrorMessages": [],
            "StatusMesssages": [],
            "TotalStatusMessages": 0,
            "TotalErrors": 0
        }
    }
Response Values:
  • ExpiresIn - The number of seconds which this signin token is valid for. After this point a new authentication request must be made.
  • Token - This is the signin token which must be used on subsequent api calls. Failure to supply a valid signin token will result in a failed api call.
  • APIEndpoint - The url used to acess web services.
Sample Code:
                                                
    var client = new RestClient("https://apinie.sensorpro.net/auth/sys/Signin");
    client.Timeout = -1;
    var request = new RestRequest(Method.POST);
    request.AddHeader("Content-Type", "application/json");
    request.AddHeader("x-apikey", "5f9b1bb2-1850-42a6-a6f7-7848b8d3708d");
    request.AddParameter("application/json", "{    "Organization": "YOURORGANIZATION",    "User": "YOURUSER",    "Password":"YOURPASSWORD"}",  ParameterType.RequestBody);
    IRestResponse response = client.Execute(request);
    Console.WriteLine(response.Content);
                                                
                                                
                                                
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://apinie.sensorpro.net/auth/sys/Signin',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'
{
"Organization": "YOURORGANIZATION",
"User": "YOURUSER",
"Password":"YOURPASSWORD"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'x-apikey: 5f9b1bb2-1850-42a6-a6f7-7848b8d3708d'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
                                                
                                                
                                                
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{    "Organization": "YOURORGANIZATION",    "User": "YOURUSER",    "Password":"YOURPASSWORD"}");
Request request = new Request.Builder()
.url("https://apinie.sensorpro.net/auth/sys/Signin")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("x-apikey", "5f9b1bb2-1850-42a6-a6f7-7848b8d3708d")
.build();
Response response = client.newCall(request).execute();
                                                
                                                

LOGOFF

Use this API call to log off the session.

Logoff Endpoint
Method: POST
https://apinie.sensorpro.net/auth/sys/logoff/[Token]

Copy to Clipboard

  • [Token] - replace with the access token returned by the signin.
Header Values
Header Example Description
Content-Type application/json;  
Response

There is no response for this API call.

Sample Code:
                                            var client = new RestClient("https://apinie.sensorpro.net/auth/sys/logoff/[Token]");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json;");
IRestResponse response = client.Execute(request);
													
                                                
                                            
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://apinie.sensorpro.net/auth/sys/logoff/[Token]",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => array(
        "Content-Type: application/json;"
    
  ),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
													
                                                
                                            
														OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://apinie.sensorpro.net/auth/sys/logoff/[Token]")
  .post(null)
  .addHeader("Content-Type", "application/json;")
  .build();

Response response = client.newCall(request).execute();