REST API Documentation
Changes from v1.6
- Additional device status:
Catch detectedfor supported devices. - Additional report type:
Catch detectedfor supported devices.
About
traplinked offers a read-only and rate limited REST API for developers to fetch information in JSON format.
Basic User Flow
If a user wants to connect a traplinked device with third party software an API token is needed. With this token it's possible to request the data for all devices attached to the customer account.
To request data for specific devcies a device serial number is needed. The device serial number can be found in the web app or on the device itself. Additionally the web app will create a QR code which encodes the serial number.
In addition to fetching data of specific or all devices it's possible to fetch information for all devices of a location by default excluding devices from sub-locations. To achieve this the location path or location id must be provided in the request instead of a device serial number. A QR code containing the location path will be shown in the web app. If devices from sub-locations are needed the additional parameter include_sublocations can be used.
It's also possible to attach reports data to devices by specifying a date and time in UTC.
API Tokens
Access to the API is restricted using an API token. The token can be managed by an admin user in the settings of the web app.
Authentication
The API uses tokens to authenticate requests. All requests must be authenticated. Authentication is performed via Bearer Authentication.
Authentication: Bearer <token>
Requests
All requests must be made over HTTPS. Data can be fetched using GET requests.
Base URL
The base URL is
https://api.traplinked.com/api/v1.7
To always use the latest version of a major release the following URL can be used:
https://api.traplinked.com/api/v1
Paths
| Path | Description |
|---|---|
| /devices | Get device data |
Responses
Responses are sent in JSON format.
Devices
To get devices data the path /devices is used.
Request Parameters
Requests take either no parameter, a list of devices or a location path or a location_id as parameter. If both parameters are sent only the list of devices will be used. If location_path and location_id are given only location_path is used. In addition reports of devices can be requested.
| Name | Description | Example |
|---|---|---|
| ids | A comma separated list of devices serial numbers. | 1A11BC,DEF222 |
| location_path | An URL encoded path to a location. The path starts with a '//'. Locations and sub locations are separated by a '//'. | %2F%2Fmy%2F%2Fpath |
| location_id | The id of a location. | 30fc3989-efdf-4e58-a1dc-9bec0a399908 |
| include_sublocations | If this parameter is provided (no value is needed) devices from sub-locations of the given location_path are returned. | |
| reports_since | An optional date in UTC in the following format: 2020-01-01T12:00:00. Reports since this date will be sent. If this parameter is omitted no reports will be attached to devices. | 2020-01-01T12:00:00 |
| device_fields | A comma separated list of fields to return for a device. If this parameter is omitted all fields are returned. See device for a list of fields. If reports are requested the reports field is always returned. | name,serial_number,status |
Response
The response is a JSON object with an array of devices in the field devices. Only mandatory fields are returned for every request. Optional fields are only sent if they're available.
{
"devices": [
...
]
}
Device
| Name | Type | Optional | Description |
|---|---|---|---|
| name | String | Mandatory | Name of the device. Can be changed by the user. Default name is the serial number. |
| serial_number | String | Mandatory | Serial number of the device. Example: 1A11BC |
| type | Integer | Mandatory | The device type. See device type section for further details. |
| status | Integer | Mandatory | The status of the device. See device status section for further details. |
| battery_status | Decimal | Mandatory | Battery status of the device. A value between 0.0 and 1.0. |
| description | String | Optional | Device description. Can be changed by the user. |
| last_heartbeat | Datetime | Optional | Last time the device connected to the server in UTC. Example: 2020-01-01T12:00:00 |
| latitude | Decimal | Optional | Latitude of the device. |
| longitude | Decimal | Optional | Longitude of the device. |
| transfer_mode | Integer | Mandatory | Connection type. See transfer mode section for further details. |
| location | Location data | Optional | Location data. See location data section for further details. |
| trap_1 | Bool | Optional | Status of trap_1: "true" for triggered, "false" for not triggered |
| trap_2 | Bool | Optional | Status of trap_2: "true" for triggered, "false" for not triggered |
| operation_mode | Integer | Mandatory | Operation mode. See operation mode section for further details. |
| reports | Array of reports | Optional | Reports data. See reports data section for further details. |
Device Type
| Type | Description |
|---|---|
| 0 | JERRY |
| 1 | JERRY LoRa |
| 2 | TrapMe |
| 3 | TOM |
Device Status
| Status | Description |
|---|---|
| 0 | Device is inactive. |
| 1 | Device is active. |
| 2 | Heartbeat failed. |
| 3 | Device has triggered. |
| 4 | Battery is low. |
| 5 | Location mode is active. |
| 6 | Unstable Wi-Fi connection |
| 7 | Light infestation |
| 8 | Severe infestation |
| 9 | False triggered |
| 10 | Activity warning |
| 11 | Activity critical |
| 12 | Catch detected |
Transfer Mode
| Mode | Description |
|---|---|
| 0 | Wi-Fi |
| 1 | LoRa |
Location Data
If the device is not assigned to a location, this field is missing. If devices for a location path are requested location data is omitted, except when devices from sub-locations are requested.
| Name | Type | Optional | Description |
|---|---|---|---|
| name | String | Mandatory | The name of the location. |
| address | String | Optional | The address of the location. |
| path | String | Optional | The path to the location including the location itself. Path elements are divided by "//". E. g. "//MyLocation//MySublocation" |
Operation Modes
| Mode | Description |
|---|---|
| 0 | Snaptrap mode |
| 1 | Movement mode |
| 2 | Insect mode |
Reports Data
| Name | Type | Optional | Description |
|---|---|---|---|
| type | Integer | Mandatory | Type of report. See report type section for further details. |
| timestamp | Datetime | Mandatory | Timestamp of report in UTC. Example: 2020-01-01T12:00:00 |
| user | String | Optional | The name of the user who created the infestation report. |
| description | String | Optional | The description stored for the infestation report. |
Report Types
| Type | Description |
|---|---|
| 2 | Trap was triggered. |
| 3 | Trap was rearmed. |
| 14 | Trap was infested. |
| 15 | Light infestation |
| 16 | Servere infestation |
| 18 | Activity warning |
| 19 | Activity critical |
| 20 | Catch detected |
Errors
Errors are signaled through HTTP status codes.
| Code | Description |
|---|---|
| 200 | Successful request |
| 400 | Bad request |
| 401 | Unauthorized |
| 429 | Too many requests |
| 500 | Internal server error |
Examples
Getting all Device Data
Request
curl "https://api.traplinked.com/api/v1.7/devices?reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Response
{
"devices": [
{
"serial_number": "TESTDEVICE1",
"name": "TESTDEVICE1",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": true,
"trap_2": false,
"location": {
"name": "MyLocation",
"path": "//MyLocation"
},
"reports": [
{
"type": 14,
"timestamp": "2021-02-02T14:44:54",
"user": "Admin API",
"description": "my description"
},
{
"type": 2,
"timestamp": "2021-01-31T06:53:29"
}
]
},
{
"serial_number": "TESTDEVICE2",
"name": "TESTDEVICE2",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": false,
"trap_2": true,
"location": {
"name": "MySublocation",
"path": "//MyLocation//MySublocation"
}
},
{
"serial_number": "TESTDEVICE3",
"name": "TESTDEVICE3",
"type": 0,
"description": "",
"battery_status": 1,
"status": 0,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": false,
"trap_2": false
}
]
}
Getting Device Data
Request
curl "https://api.traplinked.com/api/v1.7/devices?ids=TESTDEVICE1,TESTDEVICE2&reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Response
{
"devices": [
{
"serial_number": "TESTDEVICE1",
"name": "TESTDEVICE1",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": true,
"trap_2": false,
"location": {
"name": "MyLocation",
"path": "//MyLocation"
},
"reports": [
{
"type": 14,
"timestamp": "2021-02-02T14:44:54",
"user": "Admin API",
"description": "my description"
},
{
"type": 2,
"timestamp": "2021-01-31T06:53:29"
}
]
},
{
"serial_number": "TESTDEVICE2",
"name": "TESTDEVICE2",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": false,
"trap_2": true,
"location": {
"name": "MySublocation",
"path": "//MyLocation//MySublocation"
}
}
]
}
Getting Location Data
Request
curl "https://api.traplinked.com/api/v1.7/devices?location_path=%2F%2FMyLocation&reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
or
curl "https://api.traplinked.com/api/v1.7/devices?location_id=30fc3989-efdf-4e58-a1dc-9bec0a399908&reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Response
{
"devices": [
{
"serial_number": "TESTDEVICE1",
"name": "TESTDEVICE1",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": true,
"trap_2": false,
"reports": [
{
"type": 14,
"timestamp": "2021-02-02T14:44:54",
"user": "Admin API",
"description": "my description"
},
{
"type": 2,
"timestamp": "2021-01-31T06:53:29"
}
]
}
]
}
Getting Location Data with Devices from Sub-locations.
Request
curl "https://api.traplinked.com/api/v1.7/devices?location_path=%2F%2FMyLocation&reports_since=2021-01-01T00:00:00&include_sublocations" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
or
curl "https://api.traplinked.com/api/v1.7/devices?location_id=30fc3989-efdf-4e58-a1dc-9bec0a399908&reports_since=2021-01-01T00:00:00&include_sublocations" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Response
{
"devices": [
{
"serial_number": "TESTDEVICE1",
"name": "TESTDEVICE1",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": true,
"trap_2": false,
"location": {
"name": "MyLocation",
"path": "//MyLocation"
},
"reports": [
{
"type": 14,
"timestamp": "2021-02-02T14:44:54",
"user": "Admin API",
"description": "my description"
},
{
"type": 2,
"timestamp": "2021-01-31T06:53:29"
}
]
},
{
"serial_number": "TESTDEVICE2",
"name": "TESTDEVICE2",
"type": 0,
"description": "",
"battery_status": 1,
"status": 3,
"last_heartbeat": "2021-01-06T16:10:00",
"transfer_mode": 0,
"trap_1": false,
"trap_2": true,
"location": {
"name": "MySublocation",
"path": "//MyLocation//MySublocation"
}
}
]
}
Testing
To test the API connection you can use the following data:
| Description | Value |
|---|---|
| API base URL | https://api.traplinked.com/api/v1.7 |
| API token | abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012 |
| Device serial numbers | TESTDEVICE1, TESTDEVICE2, TESTDEVICE3 |
| Location path | //MyLocation |
| Location id | 30fc3989-efdf-4e58-a1dc-9bec0a399908 |
Examples
Get all devices with reports since 2021-01-01T00:00:00.
curl "https://api.traplinked.com/api/v1.7/devices?reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Get devices in location MyLocation using location_path with reports since 2021-01-01T00:00:00.
curl "https://api.traplinked.com/api/v1.7/devices?location_path=%2F%2FMyLocation&reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Get devices in location MyLocation using location_id with reports since 2021-01-01T00:00:00.
curl "https://api.traplinked.com/api/v1.7/devices?location_id=30fc3989-efdf-4e58-a1dc-9bec0a399908&reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Get devices in location MyLocation using location_path with reports since 2021-01-01T00:00:00 including sub-locations.
curl "https://api.traplinked.com/api/v1.7/devices?location_path=%2F%2FMyLocation&reports_since=2021-01-01T00:00:00&include_sublocations" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Get devices in location MyLocation using location_id with reports since 2021-01-01T00:00:00 including sub-locations.
curl "https://api.traplinked.com/api/v1.7/devices?location_id=30fc3989-efdf-4e58-a1dc-9bec0a399908&reports_since=2021-01-01T00:00:00&include_sublocations" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Get specific devices with reports since 2021-01-01T00:00:00.
curl "https://api.traplinked.com/api/v1.7/devices?ids=TESTDEVICE1,TESTDEVICE2&reports_since=2021-01-01T00:00:00" -H "Accept: application/json" -H "Authorization: Bearer abcdefghiklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789012"
Questions?
If you have questions regarding our API, please contact us at: api@traplinked.com