REST API Documentation

Changes from v1.9

  • New device type: JERRY Bait Rat
  • New operation mode: Bait
  • New report types: Activity noticed, Activity threshold reached, Bait low, Activity threshold reached and bait low, Activity threshold reset
  • New device statuses: "Bait low", "Activity critical and bait low".
  • New bait monitoring fields for JERRY Bait Rat 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.10

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
/network-devices Get network 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. Always null for JERRY Bait Rat devices.
trap_2 Bool Optional Status of trap_2: "true" for triggered, "false" for not triggered. Always null for JERRY Bait Rat devices.
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.
is_bait_monitoring_enabled Bool Optional Whether bait monitoring is enabled. Only available for JERRY Bait Rat devices, null for other device types.
bait_low_count Integer Optional Bait low count. Only available for JERRY Bait Rat devices, null for other device types.
bait_pad_activity_count Integer Optional Bait pad activity count. Only available for JERRY Bait Rat devices, null for other device types.
activity_alert_threshold Object Optional Activity alert threshold. See activity alert threshold section for further details. Only available for JERRY Bait Rat devices, null for other device types.
bait_manufacturer_and_type String Optional Bait manufacturer and type. Only available for JERRY Bait Rat devices, null for other device types.
bait_weight_grams Integer Optional Bait weight in grams. Only available for JERRY Bait Rat devices, null for other device types.
bait_calibration_weight_grams Integer Optional Remaining bait weight (threshold) calibration in grams. Only available for JERRY Bait Rat devices, null for other device types.
last_bait_replaced_at Datetime Optional Last time bait was replaced in UTC. Example: 2020-01-01T12:00:00. Only available for JERRY Bait Rat devices, null for other device types.
last_bait_replaced_by_name String Optional Name of user who last replaced bait. Only available for JERRY Bait Rat devices, null for other device types.
last_activity_reset_at Datetime Optional Last time activity was reset in UTC. Example: 2020-01-01T12:00:00. Only available for JERRY Bait Rat devices, null for other device types.
last_activity_reset_by_name String Optional Name of user who last reset activity. Only available for JERRY Bait Rat devices, null for other device types.
is_bait_available Bool Optional Whether bait is available. Only available for JERRY Bait Rat devices, null for other device types.

Device Type

Type Description
0 JERRY
1 JERRY LoRa
2 TrapMe
3 TOM
4 Trapsensor
5 JERRY Bait Rat

Device Status

Status Description Device types
0 Device is inactive. JERRY, TrapMe, JERRY LoRa, JERRY Bait Rat, Trapsensor, TOM
1 Device is active / Bait is available (JERRY Bait Rat) JERRY, TrapMe, JERRY LoRa, TOM, JERRY Bait Rat, Trapsensor
2 Heartbeat failed. JERRY, JERRY LoRa, JERRY Bait Rat, TOM
3 Device has triggered. JERRY, TrapMe, JERRY LoRa, TOM, Trapsensor
4 Battery is low. JERRY, TrapMe, JERRY LoRa, TOM, JERRY Bait Rat, Trapsensor
6 Unstable Wi-Fi connection JERRY, TOM
7 Light infestation TOM
8 Severe infestation TOM
9 False triggered JERRY LoRa, TOM, Trapsensor
10 Activity warning TOM
11 Activity critical TOM, JERRY Bait Rat
12 Catch detected JERRY LoRa, Trapsensor
13 Bait low JERRY Bait Rat
14 Activity critical and bait low JERRY Bait Rat

For JERRY Bait Rat devices, "Activity critical" (status 11) and "Activity critical and bait low" (status 14) indicate that the configured activity threshold has been reached. The activity threshold defines the number of activity events within a specific timeframe (see activity alert threshold) that triggers the status change.

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
3 Bait mode

Activity Alert Threshold

The activity alert threshold is an object with the following fields. This field is only available for JERRY Bait Rat devices and null for other device types.

Name Type Description
threshold_value Integer Activity threshold. When the number of activities exceeds this value within the specified timeframe, the device receives status 11 and report type 22 is sent
timeframe_value Integer Number of days or hours during which activities are counted toward the threshold
timeframe_type String Unit of the timeframe. Possible values: "d" (days), "h" (hours)

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 Device types
2 Trap was triggered. JERRY, TrapMe, JERRY LoRa, TOM, Trapsensor
3 Trap was rearmed / Bait was replaced (JERRY Bait Rat) JERRY, TrapMe, JERRY LoRa, JERRY Bait Rat, Trapsensor
14 Trap was infested. TrapMe
15 Light infestation TOM
16 Severe infestation TOM
17 False triggering JERRY LoRa, TOM, Trapsensor
18 Activity warning TOM
19 Activity critical TOM
20 Catch detected JERRY LoRa, Trapsensor
21 Activity noticed JERRY Bait Rat
22 Activity threshold reached JERRY Bait Rat
23 Bait low JERRY Bait Rat
24 Activity threshold reached and bait low JERRY Bait Rat
25 Activity threshold reset JERRY Bait Rat

Network Devices

To get network devices data the path /network-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 network 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) network devices from sub-locations of the given location_path are returned.
device_fields A comma separated list of fields to return for a network device. If this parameter is omitted all fields are returned. See network-device for a list of fields. network_device_serial_number,network_device_type

Response

The response is a JSON object with an array of devices in the field network_devices

{
    "network_devices": [
    ...
    ]
}

Network Device

Name Type Optional Description
serial_number String Mandatory Serial number of the device. Example: 1A11BC
description String Optional Device description. Can be changed by the user.
device_type String Mandatory The network device type.
product_identifier String Mandatory The network device product id.
status String Mandatory The status of the device. See network device status section for further details.
location Location data Optional Location data. See location data section for further details.

Network Device Status

Status Description
N/A Status is not available for this network device type
connected Network device is connected and online
disconnected Network device is disconnected and offline

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.10/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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null
    }
  ]
}

Getting Device Data

Request

curl "https://api.traplinked.com/api/v1.10/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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "location": {
        "name": "MySublocation",
        "path": "//MyLocation//MySublocation"
      }
    }
  ]
}

Getting Location Data

Request

curl "https://api.traplinked.com/api/v1.10/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.10/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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "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.10/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.10/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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "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,
      "operation_mode": 0,
      "is_bait_monitoring_enabled": null,
      "bait_low_count": null,
      "bait_pad_activity_count": null,
      "activity_alert_threshold": null,
      "bait_manufacturer_and_type": null,
      "bait_weight_grams": null,
      "bait_calibration_weight_grams": null,
      "last_bait_replaced_at": null,
      "last_bait_replaced_by_name": null,
      "last_activity_reset_at": null,
      "last_activity_reset_by_name": null,
      "is_bait_available": null,
      "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.10
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.10/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.10/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.10/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.10/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.10/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.10/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