IOT API Overview
Inside The Box IOT API is an open API for IT savvy customers to develop their own integrations with the Inside The Box platform.
The IOT API consists of two integration abilities:
-
HTTP REST API - for you to make calls to the Inside The Box backend
-
HTTP Webhooks - have the Inside The Box backend to make calls to your endpoint when events occur
HTTP REST API
Overview
The HTTP REST IOT API is designed to provide a simple, reliable, and flexible way for developers to interact with the Inside The Box platform programmatically. Whether you’re building a new integration, automating tasks, or creating custom applications, this API enables you to access and work with resources.
The API adheres to REST principles, using standard HTTP methods for working with resources. Requests and responses use JSON formatting for simplicity and compatibility across different programming languages.
Secure access is ensured through use of TLS-secured HTTP communication and API token-based authentication of requests.
IOT API HTTP REST endpoint: https://api.insidethebox.se/iotapi
HTTP verb principles
Inside The Box HTTP REST IOT API adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs for RESTful methods.
| Verb | Usage |
|---|---|
|
Used to retrieve a resource |
|
Used to create a new resource |
|
Used to replace an existing resource with a new one |
|
Used to update an existing resource, including partial updates |
|
Used to delete an existing resource |
HTTP status code principles
Inside The Box HTTP REST IOT API adheres as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.
| Status code | Usage |
|---|---|
|
The request completed successfully |
|
A new resource has been created successfully. |
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information |
|
The given API token is invalid |
|
The given API token does not have access to the resource |
|
The requested resource did not exist |
|
The given request is not acceptable to be processed |
|
The given request cannot be processed due to downstream issues behind the API |
|
The given API token’s request quota have been exceeded |
|
The given API token is not within a defined validity period, it’s either expired or not yet valid |
Errors
Whenever an error response (status code >= 400) is returned, the body will contain a String that describes the problem.
Authentication
An API token needs to be provided as an HTTP header with each request. The API token value is obtained through the Inside The Box mobile app available either from Google Play Store or Apple App Store.
The HTTP header Authorization is to be used for providing the API token. The value of the header
is to start with the word Token followed by a space and then the unique API token obtained from
the app. For example:
Authorization: Token 1NoDIq54…
Resources
A resource is an abstract name of the objects you work with through the API. The set of resources you can work with are primarily the devices you have permanent access to, i.e. locks and gateways. Each device has it’s own unique identifier, eg lockid and gatewayid respectively, this identifier is used to point out the target device to work with.
To obtain the unique identifier for each of your devices, use the Retrieve Devices method.
Retrieve Devices
A GET request is used to retrieve all gateways and locks that are accessible for the given API token.
Request headers
| Name | Description |
|---|---|
|
API token for performing the request. The header value to be provided as string: |
Example request
$ curl 'https://api.insidethebox.se/iotapi/devices' -i -X GET \
-H 'Authorization: Token 1NoDIq54...'
Response fields
| Path | Type | Description |
|---|---|---|
|
|
Array of gateway devices, see below for gateway object fields |
|
|
Array of lock devices, see below for lock object fields |
Response fields-gateway
| Path | Type | Description |
|---|---|---|
|
|
Date and time when the device entry was created. Formatted according to ISO 8601, for example |
|
|
User provided free-text description of the device |
|
|
Type of device. Value is either LOCK or GATEWAY |
|
|
User provided free-text name of the device |
|
|
Current state of the device. Value is either ACTIVE or INACTIVE |
|
|
ID of the gateway |
|
|
Current status of the gateway’s connection status. Value is either ONLINE, OFFLINE, NOT_RESPONDING, or UNDER_MAINTENANCE |
|
|
Date and time when the gateway’s connection status was changed last. Formatted according to ISO 8601, for example |
Response fields-lock
| Path | Type | Description |
|---|---|---|
|
|
Date and time when the device entry was created. Formatted according to ISO 8601, for example |
|
|
User provided free-text description of the device |
|
|
Type of device. Value is either LOCK or GATEWAY |
|
|
User provided free-text name of the device |
|
|
Current state of the device. Value is either ACTIVE or INACTIVE |
|
|
ID of the lock |
|
|
Current state of the lock’s accessibility. Value is either ACCESSIBLE, ACCESSIBLE_REMOTELY, ACCESSIBLE_REMOTELY_IS_OFFLINE, ALLOCATED_DUE_TO_AGE_RESTRICTED_DELIVERY, ALLOCATED_DUE_TO_HIGH_VALUE_DELIVERY, INACCESSIBLE_DUE_TO_LOW_POWER, or INACCESSIBLE_DUE_TO_INACTIVITY |
|
|
Is lock currently open? Value is either TRUE or FALSE |
|
|
Date and time when the lock was last opened or locked. Formatted according to ISO 8601, for example |
|
|
Current battery charge level |
Example response
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 569
{
"gateways" : [ {
"gatewayid" : "ccd8f45c-99b8-9e9e-0a0f-328a118cfe70",
"gatewayConnectionStatus" : "OFFLINE",
"created" : "2022-02-11T17:59:05+01:00",
"deviceType" : "GATEWAY",
"name" : "John Doe Test Gateway",
"state" : "ACTIVE"
} ],
"locks" : [ {
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"created" : "2019-04-26T12:35:42+02:00",
"description" : "John Doe Test Lock",
"deviceType" : "LOCK",
"state" : "ACTIVE"
} ]
}
Open Lock
A GET request is used to issue an OPEN command to a lock.
Request headers
| Name | Description |
|---|---|
|
API token for performing the request. The header value to be provided as string: |
Path parameters
| Parameter | Description |
|---|---|
|
Unique identifier for the lock to be opened. If |
Request parameters
| Parameter | Description |
|---|---|
|
Query string parameter. Number between 0 and 25 for the time in seconds the lock is to be kept open. If |
Example request
$ curl 'https://api.insidethebox.se/iotapi/lock/open/b6c11ddf-7ccc-ef2a-900b-777ccfa344bb?openDurationSeconds=15' -i -X GET \
-H 'Authorization: Token 1NoDIq54...'
Example response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Close Lock
A GET request is used to issue a CLOSE command to a lock.
Request headers
| Name | Description |
|---|---|
|
API token for performing the request. The header value to be provided as string: |
Path parameters
| Parameter | Description |
|---|---|
|
Unique identifier for the lock to be closed. If |
Example request
$ curl 'https://api.insidethebox.se/iotapi/lock/close/b6c11ddf-7ccc-ef2a-900b-777ccfa344bb' -i -X GET \
-H 'Authorization: Token 1NoDIq54...'
Example response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Register Webhook for Lock
A POST request is used to register a webhook endpoint for a lock. Multiple webhooks can be registered of the same lock.
Request headers
| Name | Description |
|---|---|
|
API token for performing the request. The header value to be provided as string: |
Path parameters
| Parameter | Description |
|---|---|
|
Unique identifier for the lock for which to trigger webhook calls for events. |
Request parameters
| Parameter | Description |
|---|---|
|
Optional boolean value true or false that determine if the webhook endpoint is to be called immediately up on registration with a registration event. Default is false. |
Request fields
| Path | Type | Description |
|---|---|---|
|
|
Hostname or IP address of the webhook endpoint URL to be called when an event triggers for a lock. Must be a valid Internet facing address. |
|
|
TCP port number of the webhook endpoint URL to be called when an event triggers for a lock. |
|
|
URI path of the webhook endpoint URL to be called when an event triggers for a lock. |
|
|
Querystring of the webhook endpoint URL to be called when an event triggers for a lock. Example: qsParam1=value1&qsParam2=value2 |
|
|
Boolean (true or false) value determining if HTTPS, i.e. SSL/TLS secured communication, is to be used for the webhook enpoint URL to be called when an event triggers for a lock. Default is false. |
|
|
JSON object with any custom headers to be apply for the webhook enpoint call when an event triggers for a lock. Example: {"customHeaderName":"custom header value"} |
Example request
$ curl 'https://api.insidethebox.se/iotapi/webhook/lock/b6c11ddf-7ccc-ef2a-900b-777ccfa344bb?triggerWebhook=false' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Token 1NoDIq54...' \
-d '{
"endpointHost" : "www.amazon.com",
"endpointPort" : 443,
"endpointPath" : "servicepath",
"endpointQuerystring" : "paramName=paramValue",
"useHttps" : true
}'
Example response
HTTP/1.1 201 Created
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
List Webhooks registered for Lock
A GET request is used to retrieve an array of webhook definitions registered for a lock.
Request headers
| Name | Description |
|---|---|
|
API token for performing the request. The header value to be provided as string: |
Path parameters
| Parameter | Description |
|---|---|
|
Unique identifier for the lock for which to read out all registered webhooks. |
Example request
$ curl 'https://api.insidethebox.se/iotapi/webhook/lock/b6c11ddf-7ccc-ef2a-900b-777ccfa344bb' -i -X GET \
-H 'Content-Type: application/json' \
-H 'Authorization: Token 1NoDIq54...'
Response fields
| Path | Type | Description |
|---|---|---|
|
|
Array of webhook definitions registered for the given |
Response fields-webhook
| Path | Type | Description |
|---|---|---|
|
|
Hostname or IP address of the webhook endpoint URL to be called when an event triggers for a lock. Must be a valid Internet facing address. |
|
|
TCP port number of the webhook endpoint URL to be called when an event triggers for a lock. |
|
|
URI path of the webhook endpoint URL to be called when an event triggers for a lock. |
|
|
Querystring of the webhook endpoint URL to be called when an event triggers for a lock. Example: qsParam1=value1&qsParam2=value2 |
|
|
Boolean (true or false) value determining if HTTPS, i.e. SSL/TLS secured communication, is to be used for the webhook enpoint URL to be called when an event triggers for a lock. Default is false. |
|
|
JSON object with any custom headers to be apply for the webhook enpoint call when an event triggers for a lock. Example: {"customHeaderName":"custom header value"} |
|
|
Unique identifier of the registered webhook |
Example response
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 262
[ {
"webhookid" : "bc240bc4-2504-496a-9b6e-39c9e3e8184c",
"endpointHost" : "www.amazon.com",
"endpointPort" : 443,
"endpointPath" : "/servicepath",
"endpointQuerystring" : "paramName=paramValue",
"customHeaders" : { },
"useHttps" : true
} ]
Remove Webhook registration for Lock
A DELETE request is used to remove a webhook registration for a lock. The required webhookid parameter is retrieved from the response of listing webhook registrations.
Request headers
| Name | Description |
|---|---|
|
API token for performing the request. The header value to be provided as string: |
Path parameters
| Parameter | Description |
|---|---|
|
Unique identifier of the webhook that is to be removed. |
Request parameters
| Parameter | Description |
|---|---|
|
Optional boolean value true or false that determine if the webhook endpoint is to be called immediately up on deletion of the webhook registration with a deregistration event. Default is false. |
Example request
$ curl 'https://api.insidethebox.se/iotapi/webhook/bc240bc4-2504-496a-9b6e-39c9e3e8184c?triggerWebhook=false' -i -X DELETE \
-H 'Content-Type: application/json' \
-H 'Authorization: Token 1NoDIq54...'
Example response
HTTP/1.1 200 OK
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
HTTP Webhooks
Overview
Webhooks are a great way to receive real-time notifications about events happening with your Inside The Box lock. Instead of constantly polling for updates, you can use the IOT API to register a webhook URL to your application, and the Inside The Box IOT API backend services will automatically make a call to your webhook endpoint with data about the event whenever it occurs. This enables instant updates, seamless automation of your systems, and eliminates the need for inefficient polling, saving resources and improving responsiveness.
IOT API supports making HTTP REST calls to your webhook endpoints.
Terminology
| Term | Description |
|---|---|
|
Something happening in relation to your lock that your Webhook Endpoint is notified about. |
|
The data about the event sent from Inside The Box IOT API to your Webhook Endpoint. |
|
A HTTP REST request initiated by Inside The Box IOT API to your Webhook Endpoint. |
|
The configuration information you provide to Inside The Box IOT API about your Webhook Endpoint. |
|
An application you have setup to listen to Webhook Calls from Inside The Box IOT API. |
|
The URL Inside The Box IOT API is to use to make Webhook Call to your Endpoint. |
Register Webhook Configuration
The supported Events, for which Webhook Calls are made, are related to locks. So, a Webhook Configuration is saved in the IOT API with a relationship to the lock you provide up on registration.
The HTTP REST IOT API contains a method for registering a Webhook Configuration.
This means that registering a Webhook Configuration requires that you have first obtained an API token to the IOT API. Then you can register a Webhook Configuration either manually by using a tool of choice, for example cURL or Postman, or let your Webhook Endpoint application make the Webhook configuration registration call.
Webhook Configration contains information about your Webhook Endpoint, e.g. hostname, port, path, etc. that your application is listening to.
Webhook Calls
Inside The Box IOT API backend supports making HTTP REST calls to your Webhook Endpoint, which means it is either a HTTP or HTTPS request and the body payload is a JSON object. The payload differs in content depending on which event triggers the call, see currently supported events and their payloads here.
Webhook Events
When a Webhook Configuration is registered for a lock, then the Inside The Box IOT API backend will automatically make a Webhook Call to the configured Webhook Endpoint when an event happens with that lock. Webhook Calls are currently triggered for the following events:
-
Delivery Dropoff
-
Delivery Pickup
-
YGM (You Got Mail)
-
Battery Power Level Warning
-
(optional) Webhook Configuration registration
-
(optional) Webhook Configuration delete
Delivery Dropoff
When a carrier dropoffs a parcel by opening your lock and laying the item in your mailbox, then that carrier’s one-time access to your lock gets consumed. This access consumption triggers a Delivery Dropoff event, which renders a call to your Webhook Endpoint. The payload is a JSON object and contains the following fields:
| Path | Type | Description |
|---|---|---|
eventType |
String |
Defining the type of event that the payload is describing. Always being |
carrierName |
String |
Name of the carrier who did the dropoff. |
carrierParcelId |
String |
Carrier’s id for the dropoff parcel. |
deliveryLock |
Lock |
JSON object defining the lock of the delivery dropoff, lock object definition. |
deliveryType |
String |
Defining the type of delivery that payload is describing. Always being |
deliveryDescription |
String |
Description of the delivery item, not always present. |
orderDescription |
String |
Description of the order, not always present. |
Example:
{
"eventType" : "DELIVERY",
"carrierName" : "Premo",
"carrierParcelId" : "09853274845",
"deliveryLock" : {
"created" : "2022-02-11T17:59:05+01:00",
"description" : "Lock at summer house",
"deviceType" : "LOCK",
"name" : "Summer house lock",
"state" : "ACTIVE",
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"lastLockOpenOrCloseTimestamp" : "2024-12-11T11:51:09+01:00",
"lockBatteryLevel" : "55"
},
"deliveryType" : "DROPOFF",
"deliveryDescription" : "Parcel from XXL",
"orderDescription" : "XXL order"
}
Delivery Pickup
When a carrier pickups a parcel by opening your lock and fethces the item from your mailbox, then that carrier’s one-time access to your lock gets consumed. This access consumption triggers a Delivery Pickup event, which renders a call to your Webhook Endpoint. The payload is a JSON object and contains the following fields:
| Path | Type | Description |
|---|---|---|
eventType |
String |
Defining the type of event that the payload is describing. Always being |
carrierName |
String |
Name of the carrier who did the pickup. |
carrierParcelId |
String |
Carrier’s id for the pickup parcel. |
deliveryLock |
Lock |
JSON object defining the lock of the delivery pickup, lock object definition. |
deliveryType |
String |
Defining the type of delivery that payload is describing. Always being |
deliveryDescription |
String |
Description of the delivery item, not always present. |
orderDescription |
String |
Description of the order, not always present. |
Example:
{
"eventType" : "DELIVERY",
"carrierName" : "ITBDelivery",
"carrierParcelId" : "274845095249",
"deliveryLock" : {
"created" : "2022-02-11T17:59:05+01:00",
"description" : "Lock at summer house",
"deviceType" : "LOCK",
"name" : "Summer house lock",
"state" : "ACTIVE",
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"lastLockOpenOrCloseTimestamp" : "2024-12-11T11:51:09+01:00",
"lockBatteryLevel" : "55"
},
"deliveryType" : "PICKUP",
"deliveryDescription" : "Return to XXL",
"orderDescription" : "Return to XXL"
}
YGM (You Got Mail)
When a lock indicates that something has been dropped into the mailbox or a carrier has delivered something, then is a Webhook Call triggered with a lock status report of the event. The payload is a JSON object and contains the following fields:
| Path | Type | Description |
|---|---|---|
eventType |
String |
Defining the type of event that the payload is describing. Always being |
lock |
Lock |
JSON object defining the lock of the battery power level warning, lock object definition. |
oneTimeAccessUsed |
Boolean |
true if a one time access was consumed as part of the YGM event, else false. |
carrierAccessUsed |
Boolean |
true if a carrier access was was used in the YouGotMail event, else false. |
Example:
{
"eventType" : "YGM",
"lock" : {
"created" : "2022-02-11T17:59:05+01:00",
"description" : "Lock at summer house",
"deviceType" : "LOCK",
"name" : "Summer house lock",
"state" : "ACTIVE",
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"lastLockOpenOrCloseTimestamp" : "2024-12-11T11:52:01+01:00",
"lockBatteryLevel" : "55"
},
"oneTimeAccessUsed": false,
"carrierAccessUsed": false
}
Lock Battery Power Level Warning
When the battery power level for a lock gets low, then is a Webhook Call triggered with a warning message. The payload is a JSON object and contains the following fields:
| Path | Type | Description |
|---|---|---|
eventType |
String |
Defining the type of event that the payload is describing. Always being |
infoType |
String |
Defining the info type for the payload. Always being |
infoMessage |
String |
Information message. |
lock |
Lock |
JSON object defining the lock of the battery power level warning, lock object definition. |
Example:
{
"eventType" : "LOCKINFO",
"infoType" : "BATTERY_LEVEL_WARNING",
"infoMessage" : "Lock battery power level is low",
"lock" : {
"created" : "2022-02-11T17:59:05+01:00",
"description" : "Lock at summer house",
"deviceType" : "LOCK",
"name" : "Summer house lock",
"state" : "ACTIVE",
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"lastLockOpenOrCloseTimestamp" : "2024-12-11T11:51:09+01:00",
"lockBatteryLevel" : "55"
}
}
Webhook Configuration registration
When a Webhook Configuration is registered through the IOT API there is an option
to provide the querystring parameter triggerWebhook=true that will trigger a Webhook Call immediately when the configuration have
been registered. The payload is a JSON object and contains the following fields:
| Path | Type | Description |
|---|---|---|
eventType |
String |
Defining the type of event that the payload is describing. Always being |
webhookOperation |
String |
Defining the operation of the Webhook Configuration. Always being |
webhookDevice |
Lock |
JSON object defining the lock to which the Webhook Configuration is attached, lock object definition. |
Example:
{
"eventType" : "WEBHOOK_CONFIGURATION",
"webhookOperation" : "CREATE",
"webhookDevice" : {
"created" : "2022-02-11T17:59:05+01:00",
"description" : "Lock at summer house",
"deviceType" : "LOCK",
"name" : "Summer house lock",
"state" : "ACTIVE",
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"lastLockOpenOrCloseTimestamp" : "2024-12-11T11:51:09+01:00",
"lockBatteryLevel" : "55"
}
}
Webhook Configuration delete
When a Webhook Configuration is deleted through the IOT API there is an option
to provide the querystring parameter triggerWebhook=true that will trigger a Webhook Call immediately when the configuration have
been removed. The payload is a JSON object and contains the following fields:
| Path | Type | Description |
|---|---|---|
eventType |
String |
Defining the type of event that the payload is describing. Always being |
webhookOperation |
String |
Defining the operation of the Webhook Configuration. Always being |
webhookDevice |
Lock |
JSON object defining the lock to which the Webhook Configuration was attached, lock object definition. |
Example:
{
"eventType" : "WEBHOOK_CONFIGURATION",
"webhookOperation" : "DELETE",
"webhookDevice" : {
"created" : "2022-02-11T17:59:05+01:00",
"description" : "Lock at summer house",
"deviceType" : "LOCK",
"name" : "Summer house lock",
"state" : "ACTIVE",
"lockid" : "b6c11ddf-7ccc-ef2a-900b-777ccfa344bb",
"lockAccessibilityState" : "ACCESSIBLE",
"isLockOpen" : false,
"lastLockOpenOrCloseTimestamp" : "2024-12-11T11:51:09+01:00",
"lockBatteryLevel" : "55"
}
}