Overview

Description

This page describes the Open API for the Samoby service.
With this API the companies can create, read, update and delete all the resources managed by the service.

Date format

All the dates must be in UTC following the next format: YYYY-MM-DD HH:MM:SS.UU (e.g 2018-01-16 11:21:22.657228)

SSL only

All requests must be done over SSL.

Authentication: OAuth 2.0

We use OAuth 2.0 to provide authorized access to our API.
Each Service Providing Partner, hereafter referred to as "Company", will be given a unique username and password to verify the source of the requests (client_id and client_secret).

HTTP Status Codes

Use of standard HTTP Status codes:
HTTP Status CodeDescription
200Operation Success
201Created
202Accepted
400Bad Request
403Forbidden
404Not Found
415Unsupported Media Type
500Internal Server Error

Extra info returned

For some HTTP Status Code, the API can return extra info following the JSON format:
{
	"error": {
		"code": ERROR_CODE,
		"message": "ERROR_INFO"
	}
}

The extra info that can be returned is:
HTTP Status CodeCodeDescription
202601Admin already exist
202602Account already exist
202603Admin does not exist
202604Member already exist
202605Device already exist
202606Waypoint already exist
202607DeviceConfiguration already exist
202608Location already exist
202609Contact already exist
202610CallLog already exist
202611Application already exist
202612ApplicationUse already exist
202613Photo already exist
202614Order already exist
202615Device already exist for the same user
202616Device already exist for another user
202617DeviceNetwork already exists
202618DeviceHardware already exists
403701Invalid user
403702Invalid scope
403703Invalid account
403704Url not allowed
403705Device does not belong to the admin
403706Invalid password
403707Account must be deleted with provisioning request
403708Waypoint does not belong to the account
403709Device has been deleted
403710Device has been wiped
403711Invalid email
403712Invalid CompanyUsername
403713CompanyUsername already exist
403714Device limit reached
403715Waypoint limit reached
403716BlockedApp limit reached
403717Account disabled
403718Wipe device not enabled
403719Key not valid
403720Read only key for admins
403721Read only key for members

Filter options for GET calls

Common parameters for GET calls:
ParameterDescription
fromTimeMin time returned
limitMax items per page. It cannot be bigger than the default value (30 in test environment)
pagePage to be returned
orderasc by default
orderbyParam used to order: id, time, name...
includeDeletedBy defalult the deleted items are not included
toTimeMax time returned

Paging info

If it is needed, the following paging info will be returned in a JSON format:
{
	"page":2,
	"limit":10,
	"recordCount":35,
	"pageCount":4,
	"next":"https://testrest.samtrace.com/applications/?limit=10&page=3",
	"prev":"https://testrest.samtrace.com/applications/?limit=10&page=1"
}

Authentication: OAuth 2.0

We use OAuth 2.0 to provide authorized access to our API.

Authorization Token (step A)

URL:/oauth2/token
Description:Check if the user exists and return Password Options (cost, salt and cnonce needed) to create the password
Methods Allowed:POST
JSON structure:
{
	"client_id":"CLIENT_ID",
	"client_secret":"CLIENT_SECRET",
	"grant_type":"password",
	"username":"XXX"
}
Example response:
{
	"error":"password_needed",
	"errorDescription":"Password needed for authentication.",
	"passwordOptions":{
		"cost":"XXX",
		"salt":"XXX",
		"cnonce":XXX
	}
}

Authorization Token (step B)

URL:/oauth2/token
Description:With cost, salt and cnonce, create the password and send the request.
The same "deviceIdentifier" parameter used for creating the access token will be assigned to the devices created with the returned token.
PHP Code to get the password:
<?php
$options = array(
	'cost' => $cost,
	'salt' => $salt
);
$hashString = password_hash($username.':'.$password, PASSWORD_BCRYPT, $options)
	.':'.$cnonce.':'
	.password_hash("POST:/oauth2/token", PASSWORD_BCRYPT, $options);
$password = password_hash($hashString, PASSWORD_BCRYPT, $options);
?>
Methods Allowed:POST
JSON structure:
{
	"client_id":"CLIENT_ID",
	"client_secret":"CLIENT_SECRET",
	"grant_type":"password",
	"username":"XXX",
	"cnonce":YYY,
	"password":"ZZZ",
	"deviceIdentifier":"BBB"
}
Example response:
{
	"access_token":"XXX",
	"expires_in":86400,
	"token_type":"Bearer",
	"scope":"all",
	"user_id":YYY,
	"refresh_token":"ZZZ"
}

Refresh Token

URL:/oauth2/token
Description:Refresh expired Token (step C)
Methods Allowed:POST
JSON structure:
{
	"client_id":"CLIENT_ID",
	"client_secret":"CLIENT_SECRET",
	"grant_type":"refresh_token",
	"refresh_token":"XXX"
}
Example response:
{
	"access_token":"XXX",
	"expires_in":86400,
	"token_type":"Bearer",
	"scope":"all",
	"user_id":YYY,
	"refresh_token":"ZZZ"
}

Resources

There are resources (objects) and a special resource (AllResources) used to get all the previous ones in a unique request.

AllResources

URL:/allResources
Description:It is used for synchronization purposes.
Except "fromTime", the other special GET parameters will be ignored for this resource.
Depending on the value of "fromTime", the request will return:
  • If no time is specified, the response will not include deleted items older than 4 days.
  • If a time is specified, it returns all the resources updated (created, modified or deleted) after "fromTime".
  • For members, the response will not include ApplicationUses, CallLogs, Locations and WebActivities.
  • For members, only the updates for her own device or member will be returned.
The response includes "syncTime" info you must use in the next requests as the "fromTime" parameter in order to sync all the resources.
The response will be the error 404 if there is no resource newer than fromTime.
Methods Allowed:GET
JSON structure:
{
	"admins":"json",
	"applicationDataUsages":"json",
	"applications":"json",
	"applicationUses":"json",
	"availableStorages":"json",
	"batteryUsages":"json",
	"boots":"json",
	"callLogs":"json",
	"contacts":"json",
	"deviceConfigurations":"json",
	"deviceDataUsage":"json",
	"deviceHardware":"json",
	"deviceNetworks":"json",
	"devices":"json",
	"locations":"json",
	"members":"json",
	"photos":"json",
	"waypoints":"json",
	"webActivities":"json",
	"syncTime":timestamp
}

Admins

URL:/admins
Description:Read or update an Admin resource
Methods Allowed:GET, PATCH/PUT
JSON structure:
{
	"id",
	"username",
	"password",
	"name",
	"email",
	"image",
	"account":{
		"id",
		"name"
	},
	"order":{
		"id"
	}
}

ApplicationDataUsages

URL:/applicationDataUsages
Description:Read an ApplicationDataUsage resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"application":{
		"id",
		"appIdentifier",			
		"version"
	},
	"creationTime",
	"fromTime",
	"toTime",
 	"mobileDataDownloaded",
 	"mobileDataDownloadedBackground",
 	"mobileDataUploaded",
 	"mobileDataUploadedBackground",
 	"wifiDownloaded",
 	"wifiDownloadedBackground",
 	"wifiUploaded",
 	"wifiUploadedBackground",
}

Applications

URL:/applications
Description:Read or update an Application resource.
If the app is blocked, blockedRange info can be included with the next info:
  • "fromTimeOfDay": Milliseconds from 00:00 to blocked time.
  • "thruTimeOfDay": Milliseconds from 00:00 to the end of blocked time.
  • "repeatAllDays": true for daily block.
  • "daysOfTheWeek": Following the order Mon:Tue:Wed:Thu:Fri:Sat:Sun, 1 if is blocked the day of the week, 0 otherwise.
Methods Allowed:GET, PATCH/PUT
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"creationTime",
	"lastModificationTime",
	"appIdentifier",
	"platform",
	"name",
	"installationTime",
	"lastUpdateTime",
	"googlePlaySource",
	"requestedPermissions",
	"blocked",
	"blockedRange":[	
		{
			"fromTimeOfDay":600000,
			"thruTimeOfDay":1000000,
			"repeatAllDays":false,
			"daysOfTheWeek":"0:1:0:1:0:0:0"
		}
	],
	"blockedLimitHour",
	"image",
	"deletionTime"
}

ApplicationUses

URL:/applicationUses
Description:Read an ApplicationUse resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"application":{
		"id",
		"appIdentifier",
		"version"	
	},
	"creationTime",
	"fromTime",
	"toTime"
}

BatteryUsages

URL:/batteryUsages
Description:Read a BatteryUsage resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"creationTime",
	"localTime",
	"value",
	"charging"
}

AvailableStorages

URL:/availableStorages
Description:Read an AvailableStorage resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	}
	"creationTime",
	"localTime",
	"internal",
	"external"
}

Boots

URL:/boots
Description:Read a Boot resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	}
	"creationTime",
	"localTime"
}

CallLogs

URL:/callLogs
Description:Read a CallLog resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"contact"{
		"id"
	},
	"creationTime",
	"type",
	"number",
	"startedTime",
	"duration"
}

Contacts

URL:/contacts
Description:Read a Contact resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"creationTime",
	"lastModificationTime",
	"contactIdentifier",
	"content",
	"image"
}

DeviceConfigurations

URL:/deviceConfigurations
Description:Read or update a DeviceConfiguration resource
Methods Allowed:GET, PATCH/PUT
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"key",
	"value",
	"lastModificationTime",
	"deletionTime"
}

DeviceDataUsages

URL:/deviceDataUsages
Description:Read a DeviceDataUsage resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"creationTime",
	"fromTime",
	"toTime",
 	"mobileDataDownloaded",
 	"mobileDataUploaded",
 	"wifiDownloaded",
 	"wifiUploaded"
}

DeviceHardware

URL:/deviceHardware
Description:Read or update a DeviceHardware resource
Methods Allowed:GET, PATCH/PUT
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"creationTime",
	"lastModificationTime",
	"cpu",
	"ram",
	"internalStorage",
	"externalStorage",
	"sim",
	"imei",
	"udid",
	"meid",
	"serialNumber",
	"macAddress",
	"bluetoothMacAddress",
	"batteryHealth",
	"modemFirmwareVersion",
	"cellularTechnology"
}

DeviceNetworks

URL:/deviceNetworks
Description:Read or update a DeviceNetwork resource
Methods Allowed:GET, PATCH/PUT
JSON structure:
{
	"id",
	"device":{
		"id"
	},
	"creationTime",
	"lastModificationTime",
	"telephoneNumber",
	"simCarrier",
	"simMCC",
	"simMNC",
	"usedCarrier",
	"usedMCC",
	"usedMNC",
	"isRoaming",
	"dualTelephoneNumber",
	"dualSimCarrier",
	"dualSimMCC",
	"dualSimMNC",
	"dualUsedCarrier",
	"dualUsedMCC",
	"dualUsedMNC",
	"dualIsRoaming",
	"carrierSettingsVersion",
	"iccid"
}

Devices

URL:/devices
Description:Read or update a Device resource
Methods Allowed:GET, PATCH/PUT
JSON structure:
{
	"id",
	"admin":{
		"id",
		"username"
	},
	"member":{
		"id",
		"username"
	},
	"userAgent":{
		"id",
		"product",
		"version",
		"platform",
	},
	"creationTime",
	"lastModificationTime",
	"deviceIdentifier",
	"name",
	"givenName",
	"brand",
	"os",
	"securityPatchVersion",
	"buildVersion",
	"gcmRegistrationId",
	"deletionTime",
	"wipeTime"
}
Extra info:In order to execute a remote wipe in the device, the following JSON must be send as a body:
{"action":"wipe","password":"XXXX"}

Locations

URL:/locations
Description:Read a Location resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"	
	},
	"waypoint":{
		"id"
	},
	"creationTime",
	"locationTime",
	"type",
	"latitude",
	"longitude",
	"accuracy"
}

Members

URL:/members
Description:Read a Member resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"creationTime",
	"locationTime",
	"username",
	"name",
	"email",
	"image"	
}

Photos

URL:/photos
Description:Read a Photo resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"		
	},
	"creationTime",
	"name",
	"modificationTime",
	"size",
	"location",
	"storagePath"
}

Waypoints

URL:/waypoint
Description:Create, read, update or delete (CRUD) a Waypoint resource
Methods Allowed:POST, GET, PATCH/PUT, DELETE
JSON structure:
{
	"id",
	"account":{
		"id",
		"name"
	},
	"creationTime",
	"locationTime",
	"name",
 	"latitude",
 	"longitude",
 	"address"
}

WebActivities

URL:/webActivities
Description:Read a WebActivity resource
Methods Allowed:GET
JSON structure:
{
	"id",
	"device":{
		"id"	
	},
	"creationTime",
	"url",
	"title",
	"domain",
	"blocked",
	"reason",
	"application":{
		"id"	
	},
	"favicon"	
}