The Push API will send every mobile-originated message from a device to your own web service as an HTTP POST.

The parameters included in the POST can vary depending on the type of device and the type of message, as described below.

You may configure multiple Push API endpoints via the Rock 7 Core user interface. Please contact your account manager if you require any assistance.

JSON or Form-Encoded

The format of the POST can be either a form-encoded post, where the parameters below will be encoded as if submitted from an HTML form.

Alternatively (and preferably) we can send a JSON document in the POST body. Here's an example:

{
  "averageCog": 0,
  "iridium_latitude": 42.0588,
  "device_type": "TIGERSHARK",
  "lon": 19.09065,
  "sog": 0.0,
  "source": "GPS",
  "battery": 82,
  "cep": 5,
  "momsn": 337,
  "id": "rLzVjdQqPgkanllZloYlnpRyKbJZONAG",
  "power": false,
  "transmit_time": "2019-01-31T14:00:13Z",
  "lat": 42.09897,
  "txAt": "2019-01-31T14:00:13Z",
  "pdop": 1.25,
  "temp": 8.0,
  "alt": 6,
  "transport": "IRIDIUM",
  "trigger": "BURST",
  "iridium_longitude": 19.0618,
  "averageSog": 0.0,
  "at": "2019-01-31T14:00:00Z",
  "serial": 21341,
  "cog": 0,
  "JWT": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJSb2NrIDciLCJpYXQiOjE1NDg5NTIzMzIsImFsdCI6IjYiLCJhdCI6IjIwMTktMDEtMzFUMTQ6MDA6MDBaIiwiYXZlcmFnZUNvZyI6IjAiLCJhdmVyYWdlU29nIjoiMC4wIiwiYmF0dGVyeSI6IjgyIiwiY2VwIjoiNSIsImNvZyI6IjAiLCJkZXZpY2VfdHlwZSI6IlRJR0VSU0hBUksiLCJpZCI6InJMelZqZFFxUGdrYW5sbFpsb1lsbnBSeUtiSlpPTkFHIiwiaXJpZGl1bV9sYXRpdHVkZSI6IjQyLjA1ODgiLCJpcmlkaXVtX2xvbmdpdHVkZSI6IjE5LjA2MTgiLCJsYXQiOiI0Mi4wOTg5NyIsImxvbiI6IjE5LjA5MDY1IiwibW9tc24iOiIzMzciLCJwZG9wIjoiMS4yNSIsInBvd2VyIjoiZmFsc2UiLCJzZXJpYWwiOiIyMTM0MSIsInNvZyI6IjAuMCIsInNvdXJjZSI6IkdQUyIsInRlbXAiOiI4LjAiLCJ0cmFuc21pdF90aW1lIjoiMjAxOS0wMS0zMVQxNDowMDoxM1oiLCJ0cmFuc3BvcnQiOiJJUklESVVNIiwidHJpZ2dlciI6IkJVUlNUIiwidHhBdCI6IjIwMTktMDEtMzFUMTQ6MDA6MTNaIn0.fxLTO4KCy-94rxVhVWrOWdXNgdWR9FLqBlBjtO2uJQlo_njbIOuiU_M8CAv4f1lon6IbbTPen4mRiSIR26S8gn3TUvPdIzzq769bVQBGNiywmwDXZbCJC3-gFi07vcvpyeXPnaEegS1M-Acd-bsC9ORzGeGTSRz5Mp9uajCJ_BSUM7ljMiZajZ6WPoVTgPwTrJ9BdUuz78qipdEQRUW1qdoubkl21SyMYRonB39CMXkA4MTrbITM1g_3viGBVglijIyVh2fumLErYP5SvwfVxNXDSuC5LFHqIszojc3gf5xwuR-fCt4CbzL_I7lOCuct3_kRiYGbUSDpU5Ytp6e1wA"
}

The JWT parameter is signed so that you can verify that the message was sent by Rock 7. The public key is:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlaWAVJfNWC4XfnRx96p9cztBcdQV6l8aKmzAlZdpEcQR6MSPzlgvihaUHNJgKm8t5ShR3jcDXIOI7er30cIN4/9aVFMe0LWZClUGgCSLc3rrMD4FzgOJ4ibD8scVyER/sirRzf5/dswJedEiMte1ElMQy2M6IWBACry9u12kIqG0HrhaQOzc6Tr8pHUWTKft3xwGpxCkV+K1N+9HCKFccbwb8okRP6FFAMm5sBbw4yAu39IVvcSL43Tucaa79FzOmfGs5mMvQfvO1ua7cOLKfAwkhxEjirC0/RYX7Wio5yL6jmykAHJqFG2HT0uyjjrQWMtoGgwv9cIcI7xbsDX6owIDAQAB
-----END PUBLIC KEY-----

Response

It is essential that your web service implementation of the Push API endpoint responds correctly. Our service requires an HTTP 200 response to indicate successful delivery - our service will then consider the message to be delivered, and no further retry attempts will be made.

Any other HTTP response will be considered a ‘temporary‘ failure, and our service will exponentially back off and retry for up to 1 week.

POST parameters

The table below describes the parameters which MAY be included.

Note that if the trigger parameter is set to CONFIG_REPORT, then you may also receive all/any of the configuration parameters described in the Get Configuration

Parameter

Description

Example/Possible Values

id

Unique ID for this report

PAjovqQGZaLRENlxJpMmnlKkpxwgdzDY

transport

Message transport method

IRIDIUM, GPRS, OTHER

imei

IMEI of Iridium device (only present for ROCKBLOCK device types)

15 digits

device_type

Type of device. This may be set to LEOPARD which refers to the family of products including
RockSTAR and Yellowbrick v3. TIGERSHARK refers to the family of devices including RockFLEET
and YB3i. GRIFFIN refers to RockAIR

LEOPARD
ROCKBLOCK
TIGERSHARK
GRIFFIN

serial

The serial number of the device.

An integer

momsn

The MOMSN of the SBD transmission. The MOMSN is a counter stored in the Iridium device,
incremented upon transmission.

An integer

transmit_time

Timestamp that the message was transmitted.

e.g. 2014-02-14T13:55:16Z

at

GPS timestamp of transmitted position.

e.g. 2014-02-14T13:54:48Z

iridium_longitude

The approximate longitude of the device, derived by the Iridium satellites.

e.g. -5.1841

iridium_latitude

The approximate latitude of the device, derived by the Iridium satellites.

e.g. 50.9009

cep

The accuracy, in km, of the Iridium derived position.

An integer

trigger

The reason for this transmission to have been triggered.

ROUTINE
MANUAL
ACTIVATION
DEACTIVATION
CONFIG_REPORT
WAYPOINT
MESSAGE
ACKNOWLEDGE
BLUETOOTH_LOSS
COLLISION
COUNTDOWN
DEAD_MAN
GEOFENCE
BUTTON
CANCEL_ALERT
POWER_LOSS
POWER_GAIN
TEMPERATURE
GENERIC
BLE_RAW
MAILBOX_CHECK
APP_MESSAGE
WATCHING_START_REQUEST
WATCHING_STOP_REQUEST

source

An indicator of whether the transmission includes a valid GPS fix.

GPS
IRIDIUM

lat

GPS latitude

50.88886

lon

GPS longitude

-1.29198

sog

Speed over ground (in knots)

e.g. 0.1

cog

Course over ground

e.g. 302

alt

GPS altitude (in metres)

e.g. 22

temp

Temperature (degrees Celsius)

e.g. 4.5

battery

Battery level, in percent

e.g. 99

power

Indicates presence of external DC power

true, false

message

A text message sent from the device.

e.g. All fine

ack_request

The id of a text message sent FROM the device, to be used when acknowledging.

e.g. 123

message_ack

The id of a text message previously sent TO the device, which the device is acknowledging.

e.g. 321

alert

Indicator of whether or not this transmission was triggered by an alert condition.

true
false

waypoint

The name of the waypoint, as selected by the device user.

e.g. Bridge

appMessageAddress

The comma-separated list of addresses for recipients specified by the user of an i360 CONNECT
App.

[email protected], 4477701233321

appMessageContent

The message content for a message sent using the i360 CONNECT App

beacons

The comma-separated list of beacons that have been observed

DA01:6969,A10A:EF01

ext_ref

An External Reference can be set in the CORE to help identify devices with a user defined ID.

Returns user specified reference

📘

Iridium position reports

We can report transmissions to you that may not have a valid GPS fix. Typically this happens if it has a poor view of the sky, but there are other occasions when it will transmit a message without a GPS position. In this case, we do get an approximate position from the Iridium network. This ranges in accuracy - often it can be within a few km, or it may be 200km out.

There is a source="GPS" or source="IRIDIUM" parameter in every element. If it's an Iridium position, you won't get sog, cog or alt parameters.

You will get a cep="123" parameter, which indicates the accuracy (in km) of the reported position.
It's necessary for us to tell you about Iridium positions, because it is possible that the tracker can report an alert with no GPS fix.