Overview

KeepTruckin makes it easy for you to access all of your fleet management data, so you can take advantage of the powerful data collection technology in the KeepTruckin ELD and mobile apps.

This document describes how to interact with our APIs. Our APIs will allow you to get data for reports, make changes to your fleet, integrate with Transportation Management Systems (TMS), and build dashboards outside of KeepTruckin to help you understand your business as a whole. Our APIs are secured with HTTPS and will provide JSON or XML formatted responses.

Getting Started

Our APIs can all be accessed through HTTPS requests to URLs like:

https://api.keeptruckin.com/v1/<endpoint>
Authentication

We use a simple and secure authentication system. You must get an API key from the KeepTruckin dashboard, and provide that key on every API request. You can create multiple API keys for your company. If a key needs to be disabled because someone with it leaves the company or if it gets shared accidentally, you can disable it in the KeepTruckin dashboard. You should not share your API key with anyone outside your organization.

To authenticate, the API client needs to include a Company API key in an HTTP header.

NOTE: API keys can be configured for “test mode” or “live mode”. A test API key will never modify data and is useful when developing your integration. Use a test API key to experiment with the API without accidentally making unwanted changes to your company profile or fleet.

Header Name Value
X-Api-Key <company api key>
Time Zone

All times are in UTC, unless a time zone is specified in an HTTP header.

Header Name Value
X-Time-Zone <time zone>
We support the following values in the X-Time-Zone header:
Header Value UTC Offset
Atlantic Time (Canada) UTC -4, uses DST
Eastern Time (US & Canada) UTC -5, uses DST
Indiana (East) UTC -5, no DST
Central Time (US & Canada) UTC -6, uses DST
Saskatchewan UTC -6, no DST
Mountain Time (US & Canada) UTC -7, uses DST
Arizona UTC -7, no DST
Pacific Time (US & Canada) UTC -8, uses DST
Alaska UTC -9, uses DST
Example:
curl -H 'X-Api-Key: 24eb4181-ee55-446b-a25b-b39777cf4d8d' -H 'X-Time-Zone: Alaska' 'https://api.keeptruckin.com/v1/users'
Request Methods

All KeepTruckin APIs use HTTP request methods to indicate the desired operation to be performed. All endpoints in this documentation will specify the request method that should be used for each API request.

GET

Use a GET request when fetching data (like listing all your company’s drivers).

POST

Use a POST request when creating new records (like adding a driver to your fleet).

PUT

Use a PUT request when updating existing records (like changing a driver’s cycle setting).

DELETE

Use a DELETE request when deleting existing records (like removing a driver from your fleet).

Response Codes

The APIs respond with codes in the 200’s, 400’s, and 500’s. Your API client should handle each class differently.

2XX

These are successful responses and indicate the API request completed without any errors.

4XX

These indicate there was a problem with the request, like missing parameters or invalid parameter values. Check the response for specific error details. Requests that respond in the 400’s should NOT be retried without modification.

5XX

These indicate there was a problem with the server and should be retried. They should only occur when the server is unreachable or misconfigured.

Response Formats

Responses can be formatted with JSON or XML. To specify the desired response format, append .json or .xml to the request path or use the Accept HTTP header. JSON is the default when nothing is specified.

JSON Examples:
curl -H 'X-Api-Key: <insert api key here>' 'https://api.keeptruckin.com/v1/users.json'
curl -H 'Accept: application/json' -H 'X-Api-Key: <insert api key here>' 'https://api.keeptruckin.com/v1/users'
XML Examples:
curl -H 'X-Api-Key: <insert api key here>' 'https://api.keeptruckin.com/v1/users.xml'
curl -H 'Accept: application/xml' -H 'X-Api-Key: <insert api key here>' 'https://api.keeptruckin.com/v1/users'
Test out an API call

You can confirm your API key works and everything is setup correctly by trying a basic request to get a list of the drivers in your fleet. Try the following command on the command line:

curl -H 'X-Api-Key: <insert api key here>' 'https://api.keeptruckin.com/v1/users?role=driver'

If you do this with an API key associated with your fleet, you should get a response like:

{
  "users": [
    {
      "user": {
        "id": 123,
        "email": "2c3e42cdaf57@keeptruckin.com",
        "first_name": "Pablo",
        "last_name": "Baskin",
        "dot_id": null,
        "phone": null,
        "phone_ext": null,
        "time_zone": "Pacific Time (US & Canada)",
        "role": "driver",
        "status": "active",
        "updated_at": "2016-02-24T06:26:00.000000Z"
      }
    },
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}

Users

1) List company users

Request format:
GET /users?role=<driver|admin|fleet_user>&name=<s>&duty_status=<off_duty|on_duty|sleeper|driving|waiting>&per_page=<i>&page_no=<i>
Request parameters:
  • role (optional | string): role of the user. valid values are admin, fleet_user & driver
  • name (optional | string): name of the user to search for
  • duty_status (optional | string): valid values are off_duty, on_duty, sleeper, driving, or waiting
  • status (optional | string): valid values are ‘active’ or ‘deactivated’
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
  • summary (optional | string): TRUE or FALSE
Example Requests:
GET /users?role="driver"&name="John%20Smith"&duty_status="driving"&per_page="100"&page_no="1"
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/users?role=driver&name=John%20Smith&duty_status=driving&per_page=100&page_no=1"
Response Status:
  • 200, 404
Response Body:
  • List of matching users
Sample JSON Request:
GET /users.json
Sample JSON Response:
{
  "users": [
    {
      "user": {
        "id": 1,
        "email": "2c3e42cdaf57@keeptruckin.com",
        "first_name": "2",
        "last_name": "Fo2",
        "dot_id": null,
        "phone": null,
        "phone_ext": null,
        "time_zone": "Pacific Time (US & Canada)",
        "role": "driver",
        "status": "active",
        "carrier_name": null,
        "carrier_street": null,
        "carrier_city": null,
        "carrier_state": null,
        "carrier_zip": null,
        "violation_alerts": "1_hour",
        "terminal_street": null,
        "terminal_city": null,
        "terminal_state": null,
        "terminal_zip": null,
        "exception_24_hour_restart": false,
        "exception_8_hour_break": false,
        "exception_wait_time": false,
        "exception_short_haul": false,
        "exception_ca_farm_school_bus": false,
        "export_combined": true,
        "export_recap": true,
        "export_odometers": true,
        "metric_units": false,
        "username": null,
        "cycle": "60_7",
        "driver_company_id": null,
        "minute_logs": false,
        "eld_mode": "none",
        "drivers_license_number": null,
        "drivers_license_state": null,
        "yard_moves_enabled": false,
        "personal_conveyance_enabled": false,
        "duty_status": "off_duty",
        "created_at": "2016-02-24T06:26:00Z",
        "updated_at": "2016-02-24T06:26:00.000000Z"
      }
    },
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}
Sample XML Request:
GET /users.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <users>
    <user>
      <id>1</id>
      <email>2c3e42cdaf57@keeptruckin.com</email>
      <first_name>2</first_name>
      <last_name>Fo2</last_name>
      <dot_id nil="true"/>
      <phone nil="true"/>
      <phone_ext nil="true"/>
      <time_zone>Pacific Time (US &amp; Canada)</time_zone>
      <role>driver</role>
      <status>active</status>
      <carrier_name nil="true"/>
      <carrier_street nil="true"/>
      <carrier_city nil="true"/>
      <carrier_state nil="true"/>
      <carrier_zip nil="true"/>
      <violation_alerts>1_hour</violation_alerts>
      <terminal_street nil="true"/>
      <terminal_city nil="true"/>
      <terminal_state nil="true"/>
      <terminal_zip nil="true"/>
      <exception_24_hour_restart>false</exception_24_hour_restart>
      <exception_8_hour_break>false</exception_8_hour_break>
      <exception_wait_time>false</exception_wait_time>
      <exception_short_haul>false</exception_short_haul>
      <exception_ca_farm_school_bus>false</exception_ca_farm_school_bus>
      <export_combined>true</export_combined>
      <export_recap>true</export_recap>
      <export_odometers>true</export_odometers>
      <metric_units>false</metric_units>
      <username nil="true"/>
      <cycle>60_7</cycle>
      <driver_company_id nil="true"/>
      <minute_logs>false</minute_logs>
      <eld_mode>none</eld_mode>
      <drivers_license_number nil="true"/>
      <drivers_license_state nil="true"/>
      <yard_moves_enabled>false</yard_moves_enabled>
      <personal_conveyance_enabled>false</personal_conveyance_enabled>
      <duty_status>off_duty</duty_status>
      <created_at>2016-02-24T06:26:00Z</created_at>
      <updated_at>2016-02-24T06:26:00.000000Z</updated_at>
    </user>
  </users>
  <pagination>
    <per_page>25</per_page>
    <page_no>1</page_no>
    <total>1</total>
  </pagination>
</data>

2) Get a specific user

Request format:
GET /users/<id>
Request parameters:
  • id (required | integer): valid user id
Response Status:
  • 200, 401, 403, 404
Response Body:

Returns user object based on user id.

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/users/158"
Sample JSON Request:
GET /users/158
Sample JSON Response:
{
  "user": {
    "id": 158,
    "email": "d77d64aa04d1@keeptruckin.com",
    "first_name": "Addison",
    "last_name": "Hahn",
    "dot_id": "1000",
    "phone": null,
    "phone_ext": null,
    "time_zone": "Mountain Time (US & Canada)",
    "role": "fleet_user",
    "status": "active",
    "duty_status": "off_duty",
    "created_at": "2016-03-16T08:22:44Z",
    "updated_at": "2016-03-16T08:22:44.226952Z"
  }
}
Sample XML Request:
GET /users/158.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <id>158</id>
    <email>d77d64aa04d1@keeptruckin.com</email>
    <first_name>Addison</first_name>
    <last_name>Hahn</last_name>
    <dot_id>1000</dot_id>
    <phone nil="true"/>
    <phone_ext nil="true"/>
    <time_zone>Mountain Time (US &amp; Canada)</time_zone>
    <role>fleet_user</role>
    <status>active</status>
    <duty_status>off_duty</duty_status>
    <created_at>2016-03-16T08:22:44Z</created_at>
    <updated_at>2016-03-16T08:22:44.226952Z</updated_at>
</data>

3) Create a new user

Request format:
POST /users
Request parameters:
  • password (required | string): password of user
  • first_name (required | string): first_name of user
  • last_name (required | string): last_name of user
  • email (required | string): email address of user (only email address OR username is required but both can be set)
  • username (required | string): username of user (only email address OR username is required but both can be set)
  • role (optional | string): role of user. valid values are (‘driver’, ‘fleet_user’, ‘admin’)
Response Status:
  • 201 - user created
  • 200 - user is valid (test mode)
  • 400 - user cannot be created
  • 403 - Forbidden
Example Request:
curl -H "X-Api-Key: 12345" -d "password=12345678&email=foo@keeptruckin.com&first_name=Foo&last_name=Bar&role=driver" "https://api.keeptruckin.com/v1/users"
Response Body:

User details

Sample JSON Request:
POST /users
Body:
{
  "password" : "123123",
  "email" : "foo@keeptruckin.com",
  "first_name" : "Foo",
  "last_name" : "Bar",
  "role" : "admin"
}
Sample JSON Response:

Same as specific user’s response.

4) Update an existing user

Request format:
PUT /users/:id
Request parameters:
  • id (required | integer): id of the user to update
  • admin/fleet_user’s params -> :email, :password, :first_name, :last_name, :dot_id, :phone, :phone_ext, :time_zone
  • Driver’s params -> :email, :password, :first_name, :last_name, :dot_id, :phone, :phone_ext, :time_zone, :cycle, :driver_company_id, :carrier_name, :carrier_street, :carrier_city, :carrier_state, :carrier_zip,:violation_alerts, :terminal_street, :terminal_city, :terminal_state, :terminal_zip, :exception_24_hour_restart,:exception_8_hour_break, :exception_wait_time, :exception_short_haul, :exception_ca_farm_school_bus, :export_combined, :export_recap, :export_odometers, :metric_units, :username, :minute_logs, :eld_mode, :drivers_license_number, :drivers_license_state, :yard_moves_enabled, :personal_conveyance_enabled
Example Request:
curl -X PUT -H "X-Api-Key: 12345" -d "password=12345678&email=foo@keeptruckin.com&first_name=Foo&last_name=Bar&role=driver" "https://api.keeptruckin.com/v1/users/104"
Response Status:
  • 200 - user updated
  • 400 - user cannot be updated
  • 403 - Forbidden
  • 404 - user not found
Response Body:

User details.

Sample Request:
PUT /users/1137
Body:
{
  "password" : "123123",
  "email" : "foo@keeptruckin.com"
}
Sample Response:

Same as specific user’s response.

Groups

1) Retrieve list of groups

Request format:
GET /groups
Request parameters:
  • page_no (optional | integer): page number for the records list. default is 1
  • per_page (optional | integer): number of records to return per page. default is 25
Response Status:
  • 200
  • 403 - Forbidden
Response Body:

Return a list of groups.

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/groups"
Sample JSON Request:
GET /groups
Sample JSON Response:
{
  "groups": [
    {
      "group": {
        "id": 6,
        "name": "Garden, Electronics & Baby",
        "company_id": 75,
        "creator": null
      }
    },
    {
      "group": {
        "id": 5,
        "name": "music",
        "company_id": 75,
        "user": {
          "id": 158,
          "full_name": "Addison Hahn",
          "email": "d77d64aa04d1@keeptruckin.com",
          "username": null,
          "status": "active",
          "role": "admin"
        }
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 2
  }
}
Sample XML Request:
GET /groups.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <groups>
        <group>
            <id>6</id>
            <name>Garden, Electronics &amp; Baby</name>
            <company_id>75</company_id>
            <creator nil="true"/>
        </group>
        <group>
            <id>5</id>
            <name>music</name>
            <company_id>75</company_id>
            <user>
                <id>158</id>
                <full_name>Addison Hahn</full_name>
                <email>d77d64aa04d1@keeptruckin.com</email>
                <username nil="true"/>
                <status>active</status>
                <role>admin</role>
            </user>
        </group>
    </groups>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>2</total>
    </pagination>
</data>

2) Get a specific group

Request format:
GET /groups/:id
Request parameters:
  • id (required | string): group id
Response Status:
  • 200
  • 400 - Not found
  • 403 - Forbidden
Response Body:

Returns group object.

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/groups"
Sample JSON Request:
GET /groups/7
Sample JSON Response:
{
  "group": {
    "id": 7,
    "name": "Grocery & Shoes",
    "company_id": 75,
    "user": {
      "id": 158,
      "full_name": "Addison Hahn",
      "email": "d77d64aa04d1@keeptruckin.com",
      "username": null,
      "status": "active",
      "role": "admin"
    }
  }
}
Sample XML Request:
GET /groups/7.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <id>7</id>
    <name>Grocery &amp; Shoes</name>
    <company_id>75</company_id>
    <user>
        <id>158</id>
        <full_name>Addison Hahn</full_name>
        <email>d77d64aa04d1@keeptruckin.com</email>
        <username nil="true"/>
        <status>active</status>
        <role>admin</role>

    </user>
</data>

3) Create group

Request format:
POST /groups
Request parameters:
  • name (required | string): group name
Response Status:
  • 201 - group created
  • 200 - group is valid (test mode)
  • 400 - cannot create group
  • 403 - user should be an admin
Response Body:

Returns group object.

Sample Request:
POST /groups
Body:
{
  "name" : "group1"
}
Example Request:
curl -H "X-Api-Key: 12345" -d "name=foo" "https://api.keeptruckin.com/v1/groups"
Sample Response:

Same as specific group’s response

4) Update group

PUT /groups/:id
Request parameters:
  • id (required | integer): id of the group to update
  • name (optional | string) : name of the group
Response Status:
  • 200 - group updated
  • 400 - cannot update group
  • 403 - Forbidden
  • 404 - group not found
Response Body:

Returns group object.

Sample Request:
PUT /groups/1
Body:
{
  "name" : "group1"
}
Example Request:
curl -X PUT -H "X-Api-Key: 12345" -d "name=foo" "https://api.keeptruckin.com/v1/groups/4"
Sample Response:

Same as create group request

5) Delete group

Request format:
DELETE /groups/:id
Request parameters:
  • id (required | integer): id of the group to delete
Response Status:
  • 200 - group deleted
  • 400 - cannot delete group
  • 403 - Forbidden
Example Request:
curl -X DELETE -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/groups/4"
Response Body:

Returns success response.

Sample Request:
DELETE /groups/1

6) Retrieve list of users in a group

Request format:
GET /groups/:id/users
Request parameters:
  • id (required | integer): id of the group
  • name (optional | string): name of the driver
  • page_no (optional | integer): page number for the records list. default is 1
  • per_page (optional | integer): number of records to return per page. default is 25
Response Status:
  • 200
  • 403 - Forbidden
Response Body:

Returns users in a group.

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/groups/4/users"
Sample JSON Request:
GET /groups/1/users
Sample JSON Response:
{
  "users": [
    {
      "user": {
        "id": 161,
        "first_name": "Alexandrea",
        "last_name": "Koch",
        "cycle": "70_8",
        "mobile_last_active_at": "2016-03-16T09:20:26Z",
        "status": "active",
        "role": "driver"
      }
    },
    {
      "user": {
        "id": 159,
        "first_name": "Anahi",
        "last_name": "Flatley",
        "cycle": "70_8",
        "mobile_last_active_at": "2016-03-16T08:23:32Z",
        "status": "active",
        "role": "driver"
      }
    },
    {
      "user": {
        "id": 160,
        "first_name": "Golden",
        "last_name": "Cummings",
        "cycle": "70_8",
        "mobile_last_active_at": "2016-03-16T09:20:19Z",
        "status": "active",
        "role": "driver"
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 3
  }
}
Sample XML Request:
GET /groups/1/users.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <users>
        <user>
            <id>161</id>
            <first_name>Alexandrea</first_name>
            <last_name>Koch</last_name>
            <cycle>70_8</cycle>
            <mobile_last_active_at>2016-03-16T09:20:26Z</mobile_last_active_at>
            <status>active</status>
            <role>driver</role>
        </user>
        <user>
            <id>159</id>
            <first_name>Anahi</first_name>
            <last_name>Flatley</last_name>
            <cycle>70_8</cycle>
            <mobile_last_active_at>2016-03-16T08:23:32Z</mobile_last_active_at>
            <status>active</status>
            <role>driver</role>
        </user>
        <user>
            <id>160</id>
            <first_name>Golden</first_name>
            <last_name>Cummings</last_name>
            <cycle>70_8</cycle>
            <mobile_last_active_at>2016-03-16T09:20:19Z</mobile_last_active_at>
            <status>active</status>
            <role>driver</role>
        </user>
    </users>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>3</total>
    </pagination>
</data>

7) Retrieve list of group vehicles

Request format:
GET /groups/:id/vehicles
Request parameters:
  • id (required | integer): id of the group
  • page_no(optional | integer): page number for the records list. default is 1
  • per_page(optional | integer): number of records to return per page. default is 25
Response Status:
  • 200
  • 403 - Forbidden
Response Body:

Returns drivers in a group.

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/groups/4/vehicles"
Sample JSON Request:
GET /groups/5/vehicles
Sample JSON Response:
{
  "vehicles": [
    {
      "vehicle": {
        "id": 24,
        "number": "V-1000",
        "status": "active",
        "make": null,
        "model": null
      }
    },
    {
      "vehicle": {
        "id": 25,
        "number": "V-1001",
        "status": "active",
        "make": null,
        "model": null
      }
    },
    {
      "vehicle": {
        "id": 26,
        "number": "V-1002",
        "status": "active",
        "make": null,
        "model": null
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 3
  }
}
Sample XML Request:
GET /groups/5/vehicles.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <vehicles>
        <vehicle>
            <id>24</id>
            <number>V-1000</number>
            <status>active</status>
            <make nil="true"/>
            <model nil="true"/>
        </vehicle>
        <vehicle>
            <id>25</id>
            <number>V-1001</number>
            <status>active</status>
            <make nil="true"/>
            <model nil="true"/>
        </vehicle>
        <vehicle>
            <id>26</id>
            <number>V-1002</number>
            <status>active</status>
            <make nil="true"/>
            <model nil="true"/>
        </vehicle>
    </vehicles>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>3</total>
    </pagination>
</data>

8) Add users to a group

Request format:
POST /groups/:id/users
Request parameters:
  • id (required | integer): id of the group
  • ids (required | integer array): array of user ids to add to the group
Response Status:
  • 200
  • 400 - fails if any of the records cannot be created
  • 403 - Forbidden
Example Request:
curl -H "X-Api-Key: 12345" -d "ids[]=66&ids[]=156" "https://api.keeptruckin.com/v1/groups/8/users"
Response Body:

Success response.

Sample Request:
POST /groups/25/users
Body:
{
  "ids": [12, 13]
}

9) Add vehicles to a group

Request format:
POST /groups/:id/vehicles
Request parameters:
  • id (required | integer): id of the group
  • ids (required | integer array): array of vehicle ids to add to the group
Response Status:
  • 200
  • 400 - fails if any of the records cannot be created
  • 403 - Forbidden
Response Body:

Success response.

Example Request:
curl -H "X-Api-Key: 12345" -d "ids[]=66&ids[]=156" "https://api.keeptruckin.com/v1/groups/8/vehicles"
Sample Request:
POST /groups/25/vehicles
Body:
{
  "ids": [12, 13]
}

10) Delete users from a group

Request format:
DELETE /groups/:id/users
Request parameters:
  • id (required | integer): id of the group
  • ids (required | integer array): array of user ids to be removed from the group
Response Status:
  • 200
  • 400 - fails if any of the records cannot be removed
  • 403 - Forbidden
Response Body:

Success response.

Example Request:
curl -X DELETE -H "X-Api-Key: 12345" -d "ids[]=156" "https://api.keeptruckin.com/v1/groups/8/users"
Sample Request:
DELETE /groups/25/users
Body:
{
  "ids": [12, 13]
}

11) Delete vehicles from a group

Request format:
DELETE /groups/:id/vehicles
Request parameters:
  • id (required | integer): id of the group
  • ids (required | integer array): array of vehicle ids to be removed from the group
Response Status:
  • 200
  • 400 - fails if any of the records cannot be removed
  • 403 - Forbidden
Response Body:

Success response.

Example Request:
curl -X DELETE -H "X-Api-Key: 12345" -d "ids[]=156" "https://api.keeptruckin.com/v1/groups/8/vehicles"
Sample Request:
DELETE /groups/25/vehicles
Body:
{
  "ids": [12, 13]
}

Driver's Available Time

1) List of given users with available times

Request format:
GET /available_time?driver_ids[]=<i>
Request parameters:
  • driver_ids (optional | integer array)
  • per_page (optional | integer): no of records to return in response. default is 25. Max is 100.
  • page_no (optional | integer): page no for the records list. default is 1
Response Status:
  • 200
  • 400
  • 403 - Forbidden
Response Body:

List of matching users with details of driver’s remaining duty time in SECONDS

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/available_time"
Sample JSON Request:
GET /v1/available_time
Sample JSON Response:
{
  "users": [
    {
      "user": {
        "id": 161,
        "first_name": "Alexandrea",
        "last_name": "Koch",
        "driver_company_id": 75,
        "duty_status": "off_duty",
        "available_time": {
          "drive": 39600,
          "shift": 50400,
          "cycle": 252000,
          "break": 28800
        },
        "recap": {
          "on_duty_duration": [
            {
              "date": "2016-07-18",
              "duration": 1200.0
            },
            {
              "date": "2016-07-17",
              "duration": 600.0
            },
            {
              "date": "2016-07-16",
              "duration": 0
            },
            {
              "date": "2016-07-15",
              "duration": 0
            },
            {
              "date": "2016-07-14",
              "duration": 0
            },
            {
              "date": "2016-07-13",
              "duration": 0
            },
            {
              "date": "2016-07-12",
              "duration": 0
            }
          ],
          "driving_duration": [
            {
              "date": "2016-07-18",
              "duration": 1200.0
            },
            {
              "date": "2016-07-17",
              "duration": 600.0
            },
            {
              "date": "2016-07-16",
              "duration": 0
            },
            {
              "date": "2016-07-15",
              "duration": 0
            },
            {
              "date": "2016-07-14",
              "duration": 0
            },
            {
              "date": "2016-07-13",
              "duration": 0
            },
            {
              "date": "2016-07-12",
              "duration": 0
            }
          ]
        },
        "last_hos_status": {
          "status": "on_duty",
          "time": "2016-07-18T07:40:00Z"
        },
        "last_cycle_reset": {
          "type": "34_hour",
          "start_time": "2016-07-16T22:00:00Z",
          "end_time": "2016-07-18T08:00:00Z"
        }
      }
    },
    {
      "user": {
        "id": 159,
        "first_name": "Anahi",
        "last_name": "Flatley",
        "driver_company_id": 75,
        "duty_status": "on_duty",
        "available_time": {
          "drive": 39600,
          "shift": 50400,
          "cycle": 252000,
          "break": 28800
        },
        "recap": {
          "on_duty_duration": [
            {
              "date": "2016-07-18",
              "duration": 0
            },
            {
              "date": "2016-07-17",
              "duration": 0
            },
            {
              "date": "2016-07-16",
              "duration": 0
            },
            {
              "date": "2016-07-15",
              "duration": 0
            },
            {
              "date": "2016-07-14",
              "duration": 0
            },
            {
              "date": "2016-07-13",
              "duration": 0
            },
            {
              "date": "2016-07-12",
              "duration": 0
            }
          ],
          "driving_duration": [
            {
              "date": "2016-07-18",
              "duration": 0
            },
            {
              "date": "2016-07-17",
              "duration": 0
            },
            {
              "date": "2016-07-16",
              "duration": 0
            },
            {
              "date": "2016-07-15",
              "duration": 0
            },
            {
              "date": "2016-07-14",
              "duration": 0
            },
            {
              "date": "2016-07-13",
              "duration": 0
            },
            {
              "date": "2016-07-12",
              "duration": 0
            }
          ]
        },
        "last_hos_status": {
          "status": "on_duty",
          "time": "2016-07-18T07:40:00Z"
        },
        "last_cycle_reset": null
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 2
  }
}
Sample XML Request:
GET /v1/available_time.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <users>
        <user>
            <id>161</id>
            <first_name>Alexandrea</first_name>
            <last_name>Koch</last_name>
            <driver_company_id>75</driver_company_id>
            <duty_status>off_duty</duty_status>
            <available_time>
                <drive>39600</drive>
                <shift>50400</shift>
                <cycle>252000</cycle>
                <break>28800</break>
            </available_time>
            <recap>
                <on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-18</date>
                        <duration>1200.0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-17</date>
                        <duration>600.0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-16</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-15</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-14</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-13</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-12</date>
                        <duration>0</duration>
                    </on_duty_duration>
                </on_duty_duration>
                <driving_duration>
                    <driving_duration>
                        <date>2016-07-18</date>
                        <duration>1200.0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-17</date>
                        <duration>600.0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-16</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-15</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-14</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-13</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-12</date>
                        <duration>0</duration>
                    </driving_duration>
                </driving_duration>
            </recap>
            <last_hos_status>
                <status>on_duty</status>
                <time>2016-07-18T07:40:00Z</time>
            </last_hos_status>
            <last_cycle_reset>
                <type>34_hour</type>
                <start_time>2016-07-16T22:00:00Z</start_time>
                <end_time>2016-07-18T08:00:00Z</end_time>
            </last_cycle_reset>
        </user>
        <user>
            <id>159</id>
            <first_name>Anahi</first_name>
            <last_name>Flatley</last_name>
            <driver_company_id>75</driver_company_id>
            <duty_status>on_duty</duty_status>
            <available_time>
                <drive>39600</drive>
                <shift>50400</shift>
                <cycle>252000</cycle>
                <break>28800</break>
            </available_time>
            <recap>
                <on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-18</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-17</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-16</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-15</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-14</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-13</date>
                        <duration>0</duration>
                    </on_duty_duration>
                    <on_duty_duration>
                        <date>2016-07-12</date>
                        <duration>0</duration>
                    </on_duty_duration>
                </on_duty_duration>
                <driving_duration>
                    <driving_duration>
                        <date>2016-07-18</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-17</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-16</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-15</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-14</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-13</date>
                        <duration>0</duration>
                    </driving_duration>
                    <driving_duration>
                        <date>2016-07-12</date>
                        <duration>0</duration>
                    </driving_duration>
                </driving_duration>
            </recap>
            <last_hos_status>
                <status>on_duty</status>
                <time>2016-07-18T07:40:00Z</time>
            </last_hos_status>
            <last_cycle_reset nil="true"/>
        </user>
    </users>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>2</total>
    </pagination>
</data>

HOS Violations

1) List of hos violations for a company’s users

Request format:
GET /v1/hos_violations?driver_ids[]=<i>&violation_types[]=<s>&min_start_time=<t>&max_start_time=<t>
Request parameters:
  • min_start_time (optional | datetime): start time begin. default is (current time - 1 day)
  • max_start_time (optional | datetime): start time end. default is current time.
  • violation_types (optional | string array): list of violations
  • driver_ids (optional | integer array)
  • per_page (optional | integer): no of records to return in response. default is 25. Max is 100.
  • page_no (optional | integer): page no for the records list. default is 1
Response Status:
  • 200
  • 400
  • 403 - Forbidden
Response Body:

List of matching hos_violations

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/hos_violations?min_start_time=2016-03-01"
Sample JSON Request:
GET /v1/hos_violations?min_start_time=2016-01-18
Sample JSON Response:
{
  "hos_violations": [
    {
      "hos_violation": {
        "id": 97,
        "type": "ca_duty_15",
        "start_time": "2016-03-12T19:00:00Z",
        "end_time": null,
        "name": "15 Hour On Duty Limit",
        "user": {
          "id": 156,
          "first_name": "Harold",
          "last_name": "Hoeger",
          "username": "hobart",
          "email": null,
          "driver_company_id": null,
          "status": "deactivated",
          "role": "driver"
        }
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}
Sample XML Request:
GET /v1/available_time.xml?min_start_time=2016-01-18T14%3A24%3A47%2B05%3A00
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <hos_violations>
        <hos_violation>
            <id>97</id>
            <type>ca_duty_15</type>
            <start_time>2016-03-12T19:00:00Z</start_time>
            <end_time nil="true"/>
            <name>15 Hour On Duty Limit</name>
            <user>
                <id>156</id>
                <first_name>Harold</first_name>
                <last_name>Hoeger</last_name>
                <username>hobart</username>
                <email nil="true"/>
                <driver_company_id nil="true"/>
                <status>deactivated</status>
                <role>driver</role>
            </user>
        </hos_violation>
    </hos_violations>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>1</total>
    </pagination>
</data>

Driver Current Locations

1) List of drivers with current location & current vehicle

Request format:
GET /driver_locations?driver_ids[]=<i>
Request parameters:
  • driver_ids (optional | integer array)
  • per_page (optional | integer): no of records to return in response. default is 25. Max is 100.
  • page_no (optional | integer): page no for the records list. default is 1
Response Status:
  • 200
  • 400
  • 403 - Forbidden
Response Body:

List of matching users with details of current locations

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/driver_locations"
Sample JSON Request:
GET /v1/driver_locations
Sample JSON Response:
{
  "users": [
    {
      "user": {
        "id": 156,
        "first_name": "Harold",
        "last_name": "Hoeger",
        "username": "hobart",
        "email": null,
        "driver_company_id": null,
        "status": "deactivated",
        "role": "driver",
        "current_location": {
          "lat": -59.8708336274616,
          "lon": -91.2958210901819,
          "description": "Washington, AZ",
          "located_at": "2016-03-17T12:12:07Z"
         },
        "current_vehicle": {
          "id": 32,
          "number": "V-1000",
          "status": "active",
          "make": null,
          "model": null
        }
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}
Sample XML Request:
GET /v1/driver_locations.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <users>
        <user>
            <id>156</id>
            <first_name>Harold</first_name>
            <last_name>Hoeger</last_name>
            <username>hobart</username>
            <email nil="true"/>
            <driver_company_id nil="true"/>
            <status>deactivated</status>
            <role>driver</role>
            <current_location>
                <id>205783</id>
                <lat>-59.8708336274616</lat>
                <lon>-91.2958210901819</lon>
                <description>Washington, NZ</description>
                <located_at>2016-03-17T12:12:07Z</located_at>
            </current_location>
            <current_vehicle>
                <id>32</id>
                <number>V-1000</number>
                <status>active</status>
                <make nil="true"/>
                <model nil="true"/>
            </current_vehicle>
        </user>
    </users>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>1</total>
    </pagination>
</data>

Vehicle Locations

1) List of vehicles with current location and current driver

Request format:
GET /vehicle_locations?vehicle_ids[]=<i>
Request parameters:
  • vehicle_ids (optional | integer array)
  • per_page (optional | integer): no of records to return in response. default is 25. Max is 100.
  • page_no (optional | integer): page no for the records list. default is 1
Response Status:
  • 200
  • 400
  • 403 - Forbidden
Response Body:

List of matching vehicles with details of current locations

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/vehicle_locations"
Sample JSON Request:
GET /v1/vehicle_locations
Sample JSON Response:
{
  "vehicles": [
    {
      "vehicle": {
        "id": 23,
        "number": "V-1000",
        "year": null,
        "make": null,
        "model": null,
        "vin": null,
        "current_location": {
          "id": "af5b6e0d-c442-414c-88d2-d95e5cb7affe",
          "lat": 47.565647,
          "lon": -122.276261,
          "description": "Seattle, WA",
          "located_at": "2016-03-17T12:12:07Z",
          "bearing": 90.0,
          "type": "vehicle_moving",
          "speed": 65.1,
          "engine_hours": 123.56,
          "fuel": 121.33,
          "odometer": 456.22
         },
        "current_driver": {
          "id": 104,
          "first_name": "Jensen",
          "last_name": "Effertz",
          "username": null,
          "email": "6b6cf86e12d4@keeptruckin.com",
          "driver_company_id": null,
          "status": "deactivated",
          "role": "driver"
        }
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}
Sample XML Request:
GET /v1/vehicle_locations.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <vehicles>
        <vehicle>
            <id>23</id>
            <number>V-1000</number>
            <year nil="true"/>
            <make nil="true"/>
            <model nil="true"/>
            <vin nil="true"/>
            <current_location>
                <id>af5b6e0d-c442-414c-88d2-d95e5cb7affe</id>
                <lat>47.565647</lat>
                <lon>-122.276261</lon>
                <description>Seattle, WA</description>
                <located_at>2016-03-17T12:12:07Z</located_at>
                <bearing>90.0</bearing>
                <type>vehicle_moving</type>
                <speed>65.1</speed>
                <engine_hours>123.56</engine_hours>
                <fuel>121.33</fuel>
                <odometer>456.22</odometer>
            </current_location>
            <current_driver>
                <id>104</id>
                <first_name>Jensen</first_name>
                <last_name>Effertz</last_name>
                <username nil="true"/>
                <email>6b6cf86e12d4@keeptruckin.com</email>
                <driver_company_id nil="true"/>
                <status>deactivated</status>
                <role>driver</role>
            </current_driver>
        </vehicle>
    </vehicles>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>1</total>
    </pagination>
</data>

2) Single day location histories of a vehicle

Request format:
GET /vehicle_locations/<id>
Request parameters:
  • id (required | integer): valid vehicle id
  • date (required | date): Date of location history (Single Day)
Response Status:
  • 200
  • 400
  • 403 - Forbidden
  • 404 - vehicle not found
Response Body:

Single day location histories of vehicle

Example Request:
curl -H "X-Api-Key: 12345" -d "date=2016-05-24" "https://api.keeptruckin.com/v1/vehicle_locations/53"
Sample JSON Request:
GET /v1/vehicle_locations/53
Sample JSON Response:
{
  "location_histories": [
    {
      "location_history": {
        "id": "af5b6e0d-c442-414c-88d2-d95e5cb7affe",
        "located_at": "2016-05-24T06:01:11Z",
        "lat": 123.0,
        "lon": 456.0,
        "bearing": 1.24,
        "engine_hours": 234.22,
        "type": "vehicle_moving",
        "description": "6.2 mi N of San Francisco, CA",
        "speed": 50.1,
        "odometer": 7.58693991,
        "fuel": 2.96665156
      },
      "location_history": {
        "id": "d1671b6d-d2ba-49f4-b8c3-8d0782a50d44",
        "located_at": "2016-05-24T09:01:11Z",
        "lat": 123.0,
        "lon": 456.0,
        "bearing": 2.24,
        "engine_hours": 244.22,
        "type": "breadcrumb",
        "description": "6.2 mi N of San Francisco, CA",
        "speed": 40.4,
        "odometer": 5.58623553,
        "fuel": 1.34645126
      }
    }
  ]
}
Sample XML Request:
GET /v1/vehicle_locations.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <location_histories>
        <location_history>
            <id>af5b6e0d-c442-414c-88d2-d95e5cb7affe</id>
            <located_at>2016-05-24T06:01:11Z</located_at>
            <loc>123.0</loc>
            <lan>456.0</lon>
            <bearing>1.24</bearing>
            <engine_hours>234.22</engine_hours>
            <type>vehicle_moving</type>
            <description>6.2 mi N of San Francisco, CA</description>
            <speed>50.1</speed>
            <odometer>7.58693991</odometer>
            <fuel> 2.96665156</fuel>
        </location_history>
        <location_history>
            <id>d1671b6d-d2ba-49f4-b8c3-8d0782a50d44</id>
            <located_at>2016-05-24T09:01:11Z</located_at>
            <loc>123.0</loc>
            <lan>456.0</lon>
            <bearing>2.24</bearing>
            <engine_hours>244.22</engine_hours>
            <type>breadcrumb</type>
            <description>6.2 mi N of San Francisco, CA</description>
            <speed>40.4</speed>
            <odometer>5.58623553</odometer>
            <fuel> 1.34645126</fuel>
        </location_history>
    </location_histories>
</data>

Send Messages

1) Send a Message

Request format:
POST /messages
Request parameters:
  • recipient_id (required | integer) *these are the same as id in the user API
  • body (required | string)
Request Headers:
HTTP_X_USER_ID(optional) default: admin. messages/emails will be sent on behalf of this user.
Response Status:
  • 201 - Message sent
  • 400 - Error occurred
  • 403 - Forbidden
  • 404 - recipient not found
Example Request:
curl -X POST -H "X-Api-Key: 12345" -d "recipient_id=1&body=hello, this is a test /'message/'" "https://api.keeptruckin.com/v1/messages"
Sample Request:
POST /v1/messages
Body:
{
  "recipient_id": 1,
  "body" : "hello, this is a test /'message/'"
}
Sample Response:
{
  "success": true
}

Inspection Reports

1) List of inspection reports

Request format:
GET /inspection_reports
Request parameters:
  • driver_ids (optional | string): ids of drivers to search for
  • vehicle_ids (optional | string): ids of vehicles to search for
  • start_date (optional | string): start date of report. default is 1 week ago
  • end_date (optional | string): end date of report. default is current date
  • status (optional | string): valid values are: all, with_defects, with_no_defects, with_signature_missing, unknown, harmless, corrected
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /inspection_reports?start_date=2016-10-3&end_date=2016-10-10&per_page="100"&page_no="1"
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/inspection_reports?start_date=2016-10-3&end_date=2016-10-10&per_page=100&page_no=1"
Response Status:
  • 200, 404
Response Body:
  • List of matching inspection reports
Sample JSON Request:
GET /inspection_reports.json
Sample JSON Response:
{
  "inspection_reports": [
    {
      "inspection_report": {
        "id": 9,
        "date": "2016-07-22",
        "time": "2016-07-22T14:00:00Z",
        "odometer": null,
        "carrier_name": "Demo Carrier",
        "vehicle_number": "Demo Vehicle",
        "trailer_nums": [
          "17"
        ],
        "location": "Omaha, NE",
        "city": "Omaha",
        "state": "NE",
        "status": "corrected",
        "mechanic_signed_at": "2016-07-22T14:00:00Z",
        "mechanic_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/mechanic_signature_upload/9/open-uri20160712-30633-thc30n?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "driver_signed_at": "2016-07-22T14:00:00Z",
        "driver_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/driver_signature_upload/9/open-uri20160729-30645-1jeoj77?AWSAccessKeyId=AKIAJH12345&Expires=1481274629&Signature=Qi1mXnl0ylJ5tCuds789Ocq44L4%3D",
        "defects": [
          {
            "defect": {
              "id": 5,
              "area": "tractor",
              "category": "Mirrors",
              "notes": null
            }
          },
          {
            "defect": {
              "id": 6,
              "area": "tractor",
              "category": "Oil Level",
              "notes": null
            }
          }
        ],
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669"
        },
        "mechanic": {
          "id": 12,
          "first_name": "Joe",
          "last_name": "Williams",
          "username": null,
          "email": "joe@example.com",
          "driver_company_id": null,
          "status": "active",
          "role": "admin"
        },
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": null,
          "status": "active",
          "role": "driver"
        }
      }
    }
  ],
  "per_page": 25,
  "page_no": 1,
  "total": 3
}
Sample XML Request:
GET /users.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <inspection_reports>
        <inspection_report>
            <id>9</id>
            <date>2016-07-22</date>
            <time>2016-07-22T14:00:00Z</time>
            <odometer nil="true"/>
            <carrier_name>Demo Carrier</carrier_name>
            <vehicle_number>Demo Vehicle</vehicle_number>
            <trailer_nums>
                <trailer_num>17</trailer_num>
            </trailer_nums>
            <location>Omaha, NE</location>
            <city>Omaha</city>
            <state>NE</state>
            <status>corrected</status>
            <mechanic_signed_at>2016-07-22T14:00:00Z</mechanic_signed_at>
            <mechanic_signature_url>https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/mechanic_signature_upload/9/open-uri20160729-30633-thc30n?AWSAccessKeyId=AKIAJHHVMD6UTJMZBMLQ&amp;Expires=1481275519&amp;Signature=dtBQJE%2Fj9891aui%2BN8RNCMZfNCc%3D</mechanic_signature_url>
            <driver_signed_at>2016-07-22T14:00:00Z</driver_signed_at>
            <driver_signature_url>https://keep-truckin-development.s3.amazonaws.com/uploads/inspection_report/driver_signature_upload/9/open-uri20160729-30633-1jeoj77?AWSAccessKeyId=AKIAJHHVMD6UTJMZBMLQ&amp;Expires=1481275519&amp;Signature=cnmAZmkCK9p2EnKKXPilPz4ntWM%3D</driver_signature_url>
            <defects>
                <defect>
                    <id>5</id>
                    <area>tractor</area>
                    <category>Mirrors</category>
                    <notes nil="true"/>
                </defect>
                <defect>
                    <id>6</id>
                    <area>tractor</area>
                    <category>Oil Level</category>
                    <notes nil="true"/>
                </defect>
            </defects>
            <vehicle>
                <id>4</id>
                <number>Demo Vehicle</number>
                <year>2016</year>
                <make>Demo</make>
                <model>Vehicle</model>
                <vin>WP0AB2966NS458669</vin>
            </vehicle>
            <mechanic>
                <id>12</id>
                <first_name>Joe</first_name>
                <last_name>Williams</last_name>
                <username nil="true"/>
                <email>joe@example.com</email>
                <driver_company_id nil="true"/>
                <status>active</status>
                <role>admin</role>
            </mechanic>
            <driver>
                <id>11</id>
                <first_name>Demo</first_name>
                <last_name>Driver</last_name>
                <username>demo_driver</username>
                <email nil="true"/>
                <driver_company_id nil="true"/>
                <status>active</status>
                <role>driver</role>
            </driver>
        </inspection_report>
      </inspection_reports>
    <per_page>25</per_page>
    <page_no>1</page_no>
    <total>3</total>
</data>

Vehicles

1) List company vehicles

Request format:
GET /vehicles
Request parameters:
  • driver_ids (optional | string): driver ids of vehicles
  • fuel_type (optional | string): vehicle’s fuel type, valid values can be ‘diesel’, ‘gasoline’ etc
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /vehicles?fuel_type=diesel&per_page=100&page_no=1
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/vehicles?fuel_type=diesel&per_page=100&page_no=1"
Response Status:
  • 200, 404
Response Body:
  • List of matching vehicles
Sample JSON Request:
GET /vehicles.json?fuel_type=diesel&per_page=100&page_no=1
Sample JSON Response:
{
  "vehicles": [
    {
      "vehicle": {
        "id": 4,
        "company_id": 5,
        "number": "Demo Vehicle",
        "status": "active",
        "ifta": true,
        "vin": "WP0AB2966NS458669",
        "make": "Demo",
        "model": "Vehicle",
        "year": "2016",
        "license_plate_state": "CA",
        "license_plate_number": "5M37250",
        "metric_units": false,
        "fuel_type": "diesel",
        "eld_device": {
          "id": 2,
          "identifier": "000074802542164638439715893965",
          "model": "lbb-1"
        },
        "current_driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": null,
          "status": "active",
          "role": "driver"
        }
      }
    }
  ],
  "pagination": {
    "per_page": 100,
    "page_no": 1,
    "total": 1
  }
}
Sample XML Request:
GET /vehicles.xml?fuel_type=diesel&per_page=100&page_no=1
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <vehicles>
        <vehicle>
            <id>4</id>
            <company_id>5</company_id>
            <number>Demo Vehicle</number>
            <status>active</status>
            <ifta>true</ifta>
            <vin>WP0AB2966NS458669</vin>
            <make>Demo</make>
            <model>Vehicle</model>
            <year>2016</year>
            <license_plate_state>CA</license_plate_state>
            <license_plate_number>5M37250</license_plate_number>
            <metric_units>false</metric_units>
            <fuel_type>diesel</fuel_type>
            <eld_device>
                <id>2</id>
                <identifier>000074802542164638439715893965</identifier>
                <model>lbb-1</model>
            </eld_device>
            <current_driver>
                <id>11</id>
                <first_name>Demo</first_name>
                <last_name>Driver</last_name>
                <username>demo_driver</username>
                <email nil="true"/>
                <driver_company_id nil="true"/>
                <status>active</status>
                <role>driver</role>
            </current_driver>
        </vehicle>
    </vehicles>
    <pagination>
        <per_page>100</per_page>
        <page_no>1</page_no>
        <total>1</total>
    </pagination>
</data>

2) Get a specific vehicle

Request format:
GET /vehicles/<id>
Request parameters:
  • id (required | integer): valid vehicle id
Response Status:
  • 200, 401, 403, 404
Response Body:

Returns vehicle object based on vehicle id.

Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/vehicles/4"
Sample JSON Request:
GET /vehicles/4
Sample JSON Response:
{
  "vehicle": {
    "id": 4,
    "company_id": 5,
    "number": "Demo Vehicle",
    "status": "active",
    "ifta": true,
    "vin": "WP0AB2966NS458669",
    "make": "Demo",
    "model": "Vehicle",
    "year": "2016",
    "license_plate_state": "CA",
    "license_plate_number": "5M37250",
    "metric_units": false,
    "fuel_type": "diesel",
    "eld_device": {
      "id": 2,
      "identifier": "000074802542164638439715893965",
      "model": "lbb-1"
    },
    "current_driver": {
      "id": 11,
      "first_name": "Demo",
      "last_name": "Driver",
      "username": "demo_driver",
      "email": null,
      "driver_company_id": null,
      "status": "active",
      "role": "driver"
    }
  }
}
Sample XML Request:
GET /vehicles/4.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <id>4</id>
    <company_id>5</company_id>
    <number>Demo Vehicle</number>
    <status>active</status>
    <ifta>true</ifta>
    <vin>WP0AB2966NS458669</vin>
    <make>Demo</make>
    <model>Vehicle</model>
    <year>2016</year>
    <license_plate_state>CA</license_plate_state>
    <license_plate_number>5M37250</license_plate_number>
    <metric_units>false</metric_units>
    <fuel_type>diesel</fuel_type>
    <eld_device>
        <id>2</id>
        <identifier>000074802542164638439715893965</identifier>
        <model>lbb-1</model>
    </eld_device>
    <current_driver>
        <id>11</id>
        <first_name>Demo</first_name>
        <last_name>Driver</last_name>
        <username>demo_driver</username>
        <email nil="true"/>
        <driver_company_id nil="true"/>
        <status>active</status>
        <role>driver</role>
    </current_driver>
</data>

3) Create a new vehicle

Request format:
POST /vehicles
Request parameters:
  • number (required | string): number of vehicle
  • eld_device_id (optional | integer): id of the eld device to attach to the vehicle
  • ifta (optional | boolean): true if vehicle is included in ifta calculations
  • metric_units (optional | boolean): true if the vehicle uses metric units
  • fuel_type (optional | string): valid values are (“diesel”, “gasoline”, “propane”, “lng”, “cng”, “ethanol”, “methanol”, “e85”, “m85”, “a55”, “biodiesel”, “other”)
  • vin (optional | string)
  • license_plate_state (optional | string)
  • license_plate_number (optional | string)
  • make (optional | string)
  • model (optional | string)
  • year (optional | string)
Response Status:
  • 201 - vehicle created
  • 400 - vehicle cannot be created
  • 403 - Forbidden
Example Request:
curl -H "X-Api-Key: 12345" -d "number=12345&eld_device_id=45&ifta=true&metric_units=true&fuel_type=diesel" "https://api.keeptruckin.com/v1/vehicles"
Response Body:

Vehicle details

Sample JSON Request:
POST /vehicles
Body:
{
  "number" : "12345",
  "ifta" : true,
  "staus" : "deactivated"
}
Sample JSON Response:

Same as specific vehicle’s response.

4) Update an existing vehicle

Request format:
PUT /vehicles/:id
Request parameters:
  • id (required | integer): id of the vehicle to update
  • ifta (optional | boolean): true if vehicle is included in ifta calculations
  • metric_units (optional | boolean): true if the vehicle uses metric units
  • status (optional | string): status of vehicle. valid values are (“active”, “deactivated”)
  • fuel_type (optional | string): valid values are (“diesel”, “gasoline”, “propane”, “lng”, “cng”, “ethanol”, “methanol”, “e85”, “m85”, “a55”, “biodiesel”, “other”)
  • vin (optional | string)
  • license_plate_state (optional | string)
  • license_plate_number (optional | string)
  • make (optional | string)
  • model (optional | string)
  • year (optional | string)
Example Request:
curl -X PUT -H "X-Api-Key: 12345" -d "eld_device_id=45&ifta=true&metric_units=true&fuel_type=diesel" "https://api.keeptruckin.com/v1/vehicles/5"
Response Status:
  • 200 - vehicle updated
  • 400 - vehicle cannot be updated
  • 403 - Forbidden
  • 404 - vehicle not found
Response Body:

Vehicle details.

Sample Request:
PUT /vehicles/5
Body:
{
  "ifta" : true,
  "staus" : "deactivated"
}
Sample Response:

Same as specific vehicle’s response.

Ifta Reports

1) Ifta Trips

Request format:
GET /ifta/trips
Request parameters:
  • start_date (optional | date) start date of ifta trips
  • end_date (optional | date) end date of ifta trips
  • jurisdictions (optional | string) jurisdiction name
  • vehicle_ids (optional | array of integers): ids of vehicles
  • fuel_type (optional | string): vehicle’s fuel type, valid values can be ‘diesel’, ‘gasoline’ etc
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /ifta/trips?fuel_type=diesel&per_page=100&page_no=1
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/ifta/trips?fuel_type=diesel&per_page=100&page_no=1"
Response Status:
  • 200, 400, 403
Response Body:
  • List of ifta trips
Sample JSON Request:
GET /ifta/trips.json
Sample JSON Response:
{
  "ifta_trips": [
    {
      "ifta_trip": {
        "id": 42,
        "date": "2016-10-05",
        "jurisdiction": "CA",
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "start_odometer": 0.6835081,
        "end_odometer": 1.3670162,
        "start_lat": 2.0,
        "start_lon": 3.0,
        "end_lat": 4.0,
        "end_lon": 5.0,
        "distance": 0.6835081,
        "time_zone": "Pacific Time (US & Canada)"
      }
    },
    {
      "ifta_trip": {
        "id": 25,
        "date": "2016-08-01",
        "jurisdiction": "NJ",
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "start_odometer": 2613.59205907,
        "end_odometer": 2719.80921781,
        "start_lat": 2.0,
        "start_lon": 3.0,
        "end_lat": 4.0,
        "end_lon": 5.0,
        "distance": 104.676158659999,
        "time_zone": "Pacific Time (US & Canada)"
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 2
  }
}
Sample XML Request:
GET /ifta/trips.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <ifta_trips>
        <ifta_trip>
            <id>42</id>
            <date>2016-10-05</date>
            <jurisdiction>CA</jurisdiction>
            <vehicle>
                <id>4</id>
                <number>Demo Vehicle</number>
                <year>2016</year>
                <make>Demo</make>
                <model>Vehicle</model>
                <vin>WP0AB2966NS458669</vin>
                <metric_units>false</metric_units>
            </vehicle>
            <start_odometer>0.6835081000000001</start_odometer>
            <end_odometer>1.3670162000000001</end_odometer>
            <start_lat>2.0</start_lat>
            <start_lon>3.0</start_lon>
            <end_lat>4.0</end_lat>
            <end_lon>5.0</end_lon>
            <distance>0.6835081000000001</distance>
            <time_zone>Pacific Time (US &amp; Canada)</time_zone>
        </ifta_trip>
        <ifta_trip>
            <id>25</id>
            <date>2016-08-01</date>
            <jurisdiction>NJ</jurisdiction>
            <vehicle>
                <id>4</id>
                <number>Demo Vehicle</number>
                <year>2016</year>
                <make>Demo</make>
                <model>Vehicle</model>
                <vin>WP0AB2966NS458669</vin>
                <metric_units>false</metric_units>
            </vehicle>
            <start_odometer>2613.5920590700002</start_odometer>
            <end_odometer>2719.8092178099996</end_odometer>
            <start_lat>2.0</start_lat>
            <start_lon>3.0</start_lon>
            <end_lat>4.0</end_lat>
            <end_lon>5.0</end_lon>
            <distance>104.67615865999939</distance>
            <time_zone>Pacific Time (US &amp; Canada)</time_zone>
        </ifta_trip>
    </ifta_trips>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>2</total>
    </pagination>
</data>

2) Ifta Summary

Request format:
GET /ifta/summary
Request parameters:
  • start_date (optional | date) start date of ifta trips
  • end_date (optional | date) end date of ifta trips
  • jurisdictions (optional | string) jurisdiction name
  • vehicle_ids (optional | array of integers): ids of vehicles
  • fuel_type (optional | string): vehicle’s fuel type, valid values can be ‘diesel’, ‘gasoline’ etc
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Response Status:
  • 200, 400, 403
Response Body:
  • List of ifta summary
Example Request:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/ifta/summary"
Sample JSON Request:
GET /ifta/summary
Sample JSON Response:
{
  "ifta_trips": [
    {
      "ifta_trip": {
        "jurisdiction": "CA",
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "distance": 0.6835081,
        "time_zone": "Pacific Time (US & Canada)"
      }
    },
    {
      "ifta_trip": {
        "jurisdiction": "NJ",
        "vehicle": {
          "id": 4,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "distance": 104.676158659999,
        "time_zone": "Pacific Time (US & Canada)"
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 2
  }
}
Sample XML Request:
GET /ifta/summary.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <ifta_trips>
        <ifta_trip>
            <jurisdiction>CA</jurisdiction>
            <vehicle>
                <id>4</id>
                <number>Demo Vehicle</number>
                <year>2016</year>
                <make>Demo</make>
                <model>Vehicle</model>
                <vin>WP0AB2966NS458669</vin>
                <metric_units>false</metric_units>
            </vehicle>
            <distance>0.6835081000000001</distance>
            <time_zone>Pacific Time (US &amp; Canada)</time_zone>
        </ifta_trip>
        <ifta_trip>
            <jurisdiction>NJ</jurisdiction>
            <vehicle>
                <id>4</id>
                <number>Demo Vehicle</number>
                <year>2016</year>
                <make>Demo</make>
                <model>Vehicle</model>
                <vin>WP0AB2966NS458669</vin>
                <metric_units>false</metric_units>
            </vehicle>
            <distance>104.67615865999939</distance>
            <time_zone>Pacific Time (US &amp; Canada)</time_zone>
        </ifta_trip>
    </ifta_trips>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>2</total>
    </pagination>
</data>

Eld Devices

1) List company eld devices

Request format:
GET /eld_devices
Request parameters:
  • identifiers (optional | array of integers): array of identifiers
  • vehicle_ids (optional | array of integers): ids of vehicles
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/eld_devices?vehicle_ids[]=1&vehicle_ids[]=2&per_page=100&page_no=1"
Response Status:
  • 200
Response Body:
  • List of matching eld devices
Sample JSON Request:
GET /eld_devices.json?vehicle_ids[]=1&vehicle_ids[]=2&per_page=100&page_no=1
Sample JSON Response:
{
  "eld_devices": [
    {
      "eld_device": {
        "vehicle": {
          "id": 1,
          "number": "Demo Vehicle",
          "year": "2016",
          "make": "Demo",
          "model": "Vehicle",
          "vin": "WP0AB2966NS458669",
          "metric_units": false
        },
        "id": 1,
        "identifier": "81323613",
        "model": "lbb-1"
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}
Sample XML Request:
GET /eld_devices.xml?vehicle_ids[]=1&vehicle_ids[]=2&per_page=100&page_no=1
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <eld_devices>
    <eld_device>
      <vehicle>
        <id>1</id>
        <number>Demo Vehicle</number>
        <year>2016</year>
        <make>Demo</make>
        <model>Vehicle</model>
        <vin>WP0AB2966NS458669</vin>
        <metric_units>false</metric_units>
      </vehicle>
      <id>1</id>
      <identifier>81323613</identifier>
      <model>lbb-1</model>
    </eld_device>
  </eld_devices>
  <pagination>
    <per_page>25</per_page>
    <page_no>1</page_no>
    <total>1</total>
  </pagination>
</data>

Logs

1) List company logs

Request format:
GET /logs
Request parameters:
  • driver_ids (optional | string): array of driver ids of logs
  • start_date (optional | string): start date of date range for logs
  • end_date (optional | string): end date of date range for logs
  • status (optional | string): valid values are ‘all, compliant, hos, form_and_manner, missing_dvirs’
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /logs?per_page=100&page_no=1
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/logs?per_page=100&page_no=1"
Response Status:
  • 200, 404
Response Body:
  • List of matching logs
Sample JSON Request:
GET /logs.json?per_page=100&page_no=1
Sample JSON Response:
{
  "logs": [
    {
      "log": {
        "id": 47,
        "date": "2016-11-22",
        "total_miles": 300,
        "metric_units": false,
        "driver_signed_at": "2016-07-16T00:05:21Z",
        "driver_signature_url": "https://keep-truckin-development.s3.amazonaws.com/uploads/log/driver_signature_upload/47/open-uri20160729-30633-1jeoj77?AWSAccessKeyId=AKIAJHHsdfsTJMZBMLQ&Expires=1485085850&Signature=YXqKF9nyfJI%2qEEq3obOLlFzsuKs0%3D",
        "time_zone": "Pacific Time (US & Canada)",
        "cycle": "70_8",
        "driver_first_name": "Demo",
        "driver_last_name": "Driver",
        "carrier_name": "Demo Carrier",
        "carrier_street": "415 Truckin St.",
        "carrier_city": "San Francisco",
        "carrier_state": "CA",
        "carrier_zip": "94105",
        "terminal_street": null,
        "terminal_city": null,
        "terminal_state": null,
        "terminal_zip": null,
        "notes": null,
        "driver_company_id": null,
        "origin": null,
        "destination": null,
        "exception_24_hour_restart": false,
        "exception_8_hour_break": false,
        "exception_wait_time": false,
        "exception_short_haul": false,
        "short_haul": false,
        "eld_mode": "logs",
        "co_driver_full_names": [],
        "odometers": {},
        "trailer_numbers": "17",
        "vehicle_numbers": "12345, 12",
        "off_duty_duration": 43200,
        "on_duty_duration": 7200,
        "sleeper_duration": 0,
        "driving_duration": 21600,
        "waiting_duration": 0,
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": null,
          "status": "active",
          "role": "driver"
        },
        "vehicles": [
          {
            "vehicle": {
              "id": 11,
              "number": "12345",
              "year": null,
              "make": null,
              "model": null,
              "vin": null,
              "metric_units": true
            }
          }
        ],
        "remarks": [
          {
            "remark": {
              "id": 1,
              "time": "2016-10-16T23:59:59Z",
              "notes": null,
              "location": null
            }
          }
        ],
        "cycle_restarts": [
          {
            "cycle_restart": {
              "id": 1,
              "start_time": "2016-10-16T08:00:00Z",
              "end_time": "2016-10-17T05:00:00Z",
              "type": "34_hour",
              "name": "34 Hour"
            }
          }
        ],
        "shipping_docs": "123ABC",
        "form_and_manner_errors": [],
        "hos_violations": [
          {
            "hos_violation": {
              "id": 12,
              "type": "canada_driving_13",
              "name": "13 Hour Driving Limit",
              "start_time": "2016-10-16T08:00:00Z",
              "end_time": "2016-10-17T07:00:00Z"
            }
          }
        ],
        "events": [
          {
            "event": {
              "id": 221,
              "type": "driving",
              "notes": null,
              "location": "Mobile, AL",
              "start_time": "2016-10-16T07:00:00Z",
              "end_time": "2016-10-16T09:00:00Z"
            }
          },
          {
            "event": {
              "id": 474,
              "type": "sleeper",
              "notes": null,
              "location": null,
              "start_time": "2016-10-16T09:00:00Z",
              "end_time": "2016-10-16T11:00:00Z"
            }
          },
          {
            "event": {
              "id": 475,
              "type": "driving",
              "notes": null,
              "location": null,
              "start_time": "2016-10-16T11:00:00Z",
              "end_time": "2016-10-17T07:00:00Z"
            }
          }
        ]
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}

Sample XML Request:
GET /logs.xml?per_page=100&page_no=1
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <logs>
        <log>
            <id>47</id>
            <date>2016-11-22</date>
            <total_miles>300</total_miles>
            <metric_units>false</metric_units>
            <driver_signed_at>2016-07-16T00:05:21Z</driver_signed_at>
            <driver_signature_url>https://keep-truckin-development.s3.amazonaws.com/uploads/log/driver_signature_upload/47/open-uri20160729-30633-1jeoj77?AWSAccessKeyId=AKIAJHHsdfsTJMZBMLQ&amp;Expires=1485086013&amp;Signature=0DBFDW3tLtgNYBYbsdfdsBmCNgQ0%3D</driver_signature_url>
            <time_zone>Pacific Time (US &amp; Canada)</time_zone>
            <cycle>70_8</cycle>
            <driver_first_name>Demo</driver_first_name>
            <driver_last_name>Driver</driver_last_name>
            <carrier_name>Demo Carrier</carrier_name>
            <carrier_street>415 Truckin St.</carrier_street>
            <carrier_city>San Francisco</carrier_city>
            <carrier_state>CA</carrier_state>
            <carrier_zip>94105</carrier_zip>
            <terminal_street nil="true"/>
            <terminal_city nil="true"/>
            <terminal_state nil="true"/>
            <terminal_zip nil="true"/>
            <notes nil="true"/>
            <driver_company_id nil="true"/>
            <origin nil="true"/>
            <destination nil="true"/>
            <exception_24_hour_restart>false</exception_24_hour_restart>
            <exception_8_hour_break>false</exception_8_hour_break>
            <exception_wait_time>false</exception_wait_time>
            <exception_short_haul>false</exception_short_haul>
            <short_haul>false</short_haul>
            <eld_mode>logs</eld_mode>
            <co_driver_full_names/>
            <odometers>
            </odometers>
            <trailer_numbers>17</trailer_numbers>
            <vehicle_numbers>12345, 12</vehicle_numbers>
            <off_duty_duration>43200</off_duty_duration>
            <on_duty_duration>7200</on_duty_duration>
            <sleeper_duration>0</sleeper_duration>
            <driving_duration>21600</driving_duration>
            <waiting_duration>0</waiting_duration>
            <driver>
                <id>11</id>
                <first_name>Demo</first_name>
                <last_name>Driver</last_name>
                <username>demo_driver</username>
                <email nil="true"/>
                <driver_company_id nil="true"/>
                <status>active</status>
                <role>driver</role>
            </driver>
            <vehicles>
                <vehicle>
                    <id>11</id>
                    <number>12345</number>
                    <year nil="true"/>
                    <make nil="true"/>
                    <model nil="true"/>
                    <vin nil="true"/>
                    <metric_units>true</metric_units>
                </vehicle>
            </vehicles>
            <remarks>
                <remark>
                    <id>1</id>
                    <time>2016-10-16T23:59:59Z</time>
                    <notes nil="true"/>
                    <location nil="true"/>
                </remark>
            </remarks>
            <cycle_restarts>
                <cycle_restart>
                    <id>1</id>
                    <start_time>2016-10-16T08:00:00Z</start_time>
                    <end_time>2016-10-17T05:00:00Z</end_time>
                    <type>34_hour</type>
                    <name>34 Hour</name>
                </cycle_restart>
            </cycle_restarts>
            <shipping_docs>123ABC</shipping_docs>
            <form_and_manner_errors/>
            <hos_violations>
                <hos_violation>
                    <hos_violation>
                        <id>12</id>
                        <type>canada_driving_13</type>
                        <name>13 Hour Driving Limit</name>
                        <start_time>2016-10-16T08:00:00Z</start_time>
                        <end_time>2016-10-17T07:00:00Z</end_time>
                    </hos_violation>
                </hos_violation>
            </hos_violations>
            <events>
                <event>
                    <event>
                        <id>221</id>
                        <type>driving</type>
                        <notes nil="true"/>
                        <location>Mobile, AL</location>
                        <start_time>2016-10-16T07:00:00Z</start_time>
                        <end_time>2016-10-16T09:00:00Z</end_time>
                    </event>
                </event>
                <event>
                    <event>
                        <id>474</id>
                        <type>sleeper</type>
                        <notes nil="true"/>
                        <location nil="true"/>
                        <start_time>2016-10-16T09:00:00Z</start_time>
                        <end_time>2016-10-16T11:00:00Z</end_time>
                    </event>
                </event>
                <event>
                    <event>
                        <id>475</id>
                        <type>driving</type>
                        <notes nil="true"/>
                        <location nil="true"/>
                        <start_time>2016-10-16T11:00:00Z</start_time>
                        <end_time>2016-10-17T07:00:00Z</end_time>
                    </event>
                </event>
            </events>
        </log>
    </logs>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>1</total>
    </pagination>
</data>

Hours of Service

1) List company hours of service

Request format:
GET /hours_of_service
Request parameters:
  • driver_ids (optional | string): array of driver ids for hours of service
  • start_date (optional | string): start date of date range for hours of service
  • end_date (optional | string): end date of date range for hours of service
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /hours_of_service?per_page=100&page_no=1
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/hours_of_service?per_page=100&page_no=1"
Response Status:
  • 200, 400
Response Body:
  • List of matching hours of service
Sample JSON Request:
GET /hours_of_service.json?per_page=100&page_no=1
Sample JSON Response:
{
  "hours_of_services": [
    {
      "hours_of_service": {
        "id": 47,
        "date": "2016-11-22",
        "off_duty_duration": 43200,
        "on_duty_duration": 7200,
        "sleeper_duration": 0,
        "driving_duration": 21600,
        "waiting_duration": 0,
        "driver": {
          "id": 11,
          "first_name": "Demo",
          "last_name": "Driver",
          "username": "demo_driver",
          "email": null,
          "driver_company_id": null,
          "status": "active",
          "role": "driver"
        }
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 1
  }
}

Sample XML Request:
GET /hours_of_service.xml?per_page=100&page_no=1
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <hours_of_services>
        <hours_of_service>
            <id>47</id>
            <date>2016-11-22</date>
            <off_duty_duration>43200</off_duty_duration>
            <on_duty_duration>7200</on_duty_duration>
            <sleeper_duration>0</sleeper_duration>
            <driving_duration>21600</driving_duration>
            <waiting_duration>0</waiting_duration>
            <driver>
                <id>11</id>
                <first_name>Demo</first_name>
                <last_name>Driver</last_name>
                <username>demo_driver</username>
                <email />
                <driver_company_id />
                <status>active</status>
                <role>driver</role>
            </driver>
        </hours_of_service>
    </hours_of_services>
    <pagination>
        <per_page>25</per_page>
        <page_no>1</page_no>
        <total>1</total>
    </pagination>
</data>

Webhooks

Webhooks allow you to be notified whenever certain actions occur within your fleet via an HTTP POST request to an endpoint of your choosing. If you have enabled webhooks for your fleet, KeepTruckin will make an HTTP POST request to your endpoint whenever the events you have setup occur.

One common use-case is vehicle location updates. If you want to be notified whenever a vehicle’s current location updates you could subscribe to the vehicle_location_updated action and you will receive a request whenever any vehicle’s location changes.

Webhook requests contain a JSON payload consisting of the action as well as any attributes relevant to the action. The list of currently support actions and their payloads are listed below.

Verifying Authenticity

Each webhook has a shared secret that KeepTruckin will use to sign the requests. The computed signature is included in the X-KT-Webhook-Signature HTTP header and can be used to verify that the request originated at KeepTruckin servers and has not been modified in-flight. You can respond with 403 if the signature does not match your computed expected value.

To compute the webhook signature, take the HMAC-SHA1 hex digest of the JSON payload using the shared secret.

Example payload:

{"action":"test"}

Example shared secret:

"8cbd43f98ba1e33c28c9"

This would have an X-KT-Webhook-Signature HTTP header value of "5e1a966298ba4f3e91847aea8746198ca0530dd2".

Example using Bash:

echo -n '{"action":"test"}' | openssl dgst -sha1 -hmac "8cbd43f98ba1e33c28c9"

Example using Ruby:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), '8cbd43f98ba1e33c28c9', '{"action":"test"}')
Expected Responses

KeepTruckin servers expect specific responses from your server to indicate the successful receipt of a webhook. Make sure that your endpoint handler responds with the appropriate response code. Additionally, your server must accept the connection within 5 seconds and respond within 10 seconds or the request will be assumed to have failed. It is up to the endpoint handler to ensure that requests are only processed once.

  • 200 or 201 - Indicates the webhook was processed successfully. KeepTruckin will consider the request final and will not retry.
  • 403 - Indicates the HMAC signature could not be verified. KeepTruckin will consider the request invalid and will not retry.
  • 4XX or 5XX - Indicates the webhook was not processed and should be retried. KeepTruckin will retry the request based on the schedule below.
Retry Schedule

KeepTruckin will make several attempts to retry failed requests using the following delays between attempts.

  • 10 seconds
  • 1 minute
  • 5 minutes
  • 10 minutes
  • 1 hour
  • 1 hour
  • 1 hour
  • 1 day
Enabling Webhooks (Test Requests)

Whenever you enable a webhook, change the URL, or change the shared secret, KeepTruckin will perform a test request to verify a successful response is received. The webhook will only be enabled if a response code of 200 or 201 is received. The test request payload is always the same:

{"action":"test"}
Supported Actions
Vehicle Current Location Updated (vehicle_location_updated)

Triggered whenever a vehicle location is received that is more recent than the current location.

Example Payload:

{
  "action": "vehicle_location_updated",
  "id": "5d3d5cf6-501f-4566-ad07-a80c05c743a7",    // unique identifier for the location object
  "vehicle_id": 123,                               // the vehicle id (foreign key)
  "located_at": "2017-01-01T12:00:00Z",            // time when the location was recorded (ISO8601 format)
  "lat": 34.123,                                   // latitude
  "lon": -84.123,                                  // longitude
  "bearing": 90.0,                                 // the direction of travel (0-360 degrees)
  "engine_hours": 123.56,                          // engine hours reported by the vehicle's ECU
  "speed": 123.5,                                  // speed reported by the vehicle's ECU
  "odometer": 2343232.23,                          // odometer reading reported by the vehicle's ECU
  "fuel": 23423.23,                                // amount of fuel used reported by the vehicle's ECU
  "type": "vehicle_moving",                        // indicates whether the location was captured when the vehicle started moving, stopped moving, or while already in motion
  "description": "3.2 mi SE of San Francisco, CA"  // description of the location
}
Vehicle Location Received (vehicle_location_received)

Triggered for all vehicle locations received regardless of whether they are the most recent or not.

Example Payload:

same as 'vehicle_location_updated' except the action is 'vehicle_location_received'

1) List Webhooks

Request format:
GET /company_webhooks
Request parameters:
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /company_webhooks
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/company_webhooks?per_page=100&page_no=1"
Response Status:
  • 200
Response Body:
  • List of configured webhooks
Sample JSON Request:
GET /company_webhooks.json
Sample JSON Response:
{
  "company_webhooks": [
    {
      "company_webhook": {
        "id": 42,
        "url": "https://keeptruckin.com/callbacktest/842b02",
        "secret": "fe8b75de0a4e5898f0011faeb8c93654",
        "format": "json",
        "actions": [
          "vehicle_location_received",
          "vehicle_location_updated"
        ],
        "enabled": false
      }
    },
    {
      "company_webhook": {
        "id": 43,
        "url": "https://keeptruckin.com/callbacktest/a6a783",
        "secret": "66a7368063cb21887f546c7af91be59c",
        "format": "json",
        "actions": [
          "vehicle_location_received",
          "vehicle_location_updated"
        ],
        "enabled": false
      }
    },
    {
      "company_webhook": {
        "id": 44,
        "url": "https://keeptruckin.com/callbacktest/53a52c",
        "secret": "4451dc96513b3a67107466dd2c4d9589",
        "format": "json",
        "actions": [
          "vehicle_location_received",
          "vehicle_location_updated"
        ],
        "enabled": false
      }
    },
    {
      "company_webhook": {
        "id": 45,
        "url": "https://keeptruckin.com/callbacktest/6fb337",
        "secret": "4177fbd88c30faaee03a4362648bd663",
        "format": "json",
        "actions": [
          "vehicle_location_received",
          "vehicle_location_updated"
        ],
        "enabled": false
      }
    },
    {
      "company_webhook": {
        "id": 46,
        "url": "https://keeptruckin.com/callbacktest/8cd6da",
        "secret": "6e41817a048b009435e5102fca17db55",
        "format": "json",
        "actions": [
          "vehicle_location_received",
          "vehicle_location_updated"
        ],
        "enabled": false
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 5
  }
}
Sample XML Request:
GET /company_webhooks.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <company_webhooks>
    <company_webhook>
      <id>42</id>
      <url>https://keeptruckin.com/callbacktest/842b02</url>
      <secret>fe8b75de0a4e5898f0011faeb8c93654</secret>
      <format>json</format>
      <actions>
        <action>vehicle_location_received</action>
        <action>vehicle_location_updated</action>
      </actions>
      <enabled>false</enabled>
    </company_webhook>
    <company_webhook>
      <id>43</id>
      <url>https://keeptruckin.com/callbacktest/a6a783</url>
      <secret>66a7368063cb21887f546c7af91be59c</secret>
      <format>json</format>
      <actions>
        <action>vehicle_location_received</action>
        <action>vehicle_location_updated</action>
      </actions>
      <enabled>false</enabled>
    </company_webhook>
    <company_webhook>
      <id>44</id>
      <url>https://keeptruckin.com/callbacktest/53a52c</url>
      <secret>4451dc96513b3a67107466dd2c4d9589</secret>
      <format>json</format>
      <actions>
        <action>vehicle_location_received</action>
        <action>vehicle_location_updated</action>
      </actions>
      <enabled>false</enabled>
    </company_webhook>
    <company_webhook>
      <id>45</id>
      <url>https://keeptruckin.com/callbacktest/6fb337</url>
      <secret>4177fbd88c30faaee03a4362648bd663</secret>
      <format>json</format>
      <actions>
        <action>vehicle_location_received</action>
        <action>vehicle_location_updated</action>
      </actions>
      <enabled>false</enabled>
    </company_webhook>
    <company_webhook>
      <id>46</id>
      <url>https://keeptruckin.com/callbacktest/8cd6da</url>
      <secret>6e41817a048b009435e5102fca17db55</secret>
      <format>json</format>
      <actions>
        <action>vehicle_location_received</action>
        <action>vehicle_location_updated</action>
      </actions>
      <enabled>false</enabled>
    </company_webhook>
  </company_webhooks>
  <pagination>
    <per_page>25</per_page>
    <page_no>1</page_no>
    <total>5</total>
  </pagination>
</data>

2) Get Webhook

Request format:
GET /company_webhooks/21
Request parameters:
  • id (required | integer) the webhook ID to return
Example Requests:
GET /company_webhooks/21
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/company_webhooks/21"
Response Status:
  • 200, 404
Response Body:
  • Company Webhook
Sample JSON Request:
GET /company_webhooks/21.json
Sample JSON Response:
{
  "company_webhook": {
    "id": 21,
    "url": "https://keeptruckin.com/callbacktest/8e763a",
    "secret": "96d52f39772408084f08604207de7ebb",
    "format": "json",
    "actions": [
      "vehicle_location_received",
      "vehicle_location_updated"
    ],
    "enabled": false
  }
}
Sample XML Request:
GET /company_webhooks/21.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <id>21</id>
  <url>https://keeptruckin.com/callbacktest/8e763a</url>
  <secret>96d52f39772408084f08604207de7ebb</secret>
  <format>json</format>
  <actions>
    <action>vehicle_location_received</action>
    <action>vehicle_location_updated</action>
  </actions>
  <enabled>false</enabled>
</data>

3) Create Webhook

Request format:
POST /company_webhooks
Request parameters:
  • url (required | string) the URL for the webhook endpoint
  • secret (optional | string) the shared secret (must be 20 characters and will be generated randomly if left blank)
  • format (optional | string) the payload format for the webhook (only “json” is supported at this time)
  • actions (optional | array of string): actions that will be supported by the webhook
  • enabled (optional | boolean): true if the webhook is enabled
Example Requests:
POST /company_webhooks
curl -X POST -H "X-Api-Key: 12345" -d "url=https%3A%2F%2Fkeeptruckin.com%2Fcallbacktest%2F38ce76" "https://api.keeptruckin.com/v1/company_webhooks"
Response Status:
  • 201, 400
Response Body:
  • The newly configured webhook
Sample JSON Request:
POST /company_webhooks.json
Sample JSON Response:
{
  "company_webhook": {
    "id": 27,
    "url": "https://keeptruckin.com/callbacktest/bd0421",
    "secret": "67298a4636cb6e07ceabf750bb63e99d",
    "format": "json",
    "actions": [
      "vehicle_location_updated"
    ],
    "enabled": false
  }
}
Sample XML Request:
POST /company_webhooks.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <id>27</id>
  <url>https://keeptruckin.com/callbacktest/bd0421</url>
  <secret>67298a4636cb6e07ceabf750bb63e99d</secret>
  <format>json</format>
  <actions>
    <action>vehicle_location_updated</action>
  </actions>
  <enabled>false</enabled>
</data>

4) Update Webhook

Request format:
PUT /company_webhooks/27
Request parameters:
  • id (required | integer) the webhook ID to update
  • url (optional | string) the URL for the webhook endpoint
  • secret (optional | string) the shared secret (must be 20 characters and will be generated randomly if left blank)
  • format (optional | string) the payload format for the webhook (only “json” is supported at this time)
  • actions (optional | array of string): actions that will be supported by the webhook
  • enabled (optional | boolean): true if the webhook is enabled
Example Requests:
PUT /company_webhooks/27?enabled=true
curl -X PUT -H "X-Api-Key: 12345" -d "enabled=true" "https://api.keeptruckin.com/v1/company_webhooks/27"
Response Status:
  • 200, 400, 404
Response Body:
  • The updated webhook object
Sample JSON Request:
PUT /company_webhooks/27.json
Sample JSON Response:
{
  "company_webhook": {
    "id": 27,
    "url": "https://keeptruckin.com/callbacktest/bd0421",
    "secret": "67298a4636cb6e07ceabf750bb63e99d",
    "format": "json",
    "actions": [
      "vehicle_location_updated"
    ],
    "enabled": true
  }
}
Sample XML Request:
PUT /company_webhooks/12.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <id>27</id>
  <url>https://keeptruckin.com/callbacktest/bd0421</url>
  <secret>67298a4636cb6e07ceabf750bb63e99d</secret>
  <format>json</format>
  <actions>
    <action>vehicle_location_updated</action>
  </actions>
  <enabled>true</enabled>
</data>

5) Delete Webhook

Request format:
DELETE /company_webhooks/27
Request parameters:
  • id (required | integer) the webhook ID to delete
Example Requests:
DELETE /company_webhooks/27
curl -X DELETE -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/company_webhooks/27"
Response Status:
  • 200, 400, 404
Response Body:
  • Success message
Sample JSON Request:
DELETE /company_webhooks/27.json
Sample JSON Response:
{
  "success": true
}
Sample XML Request:
DELETE /company_webhooks/27.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <success>true</success>
</data>

6) List Webhook Requests

Request format:
GET /company_webhook_requests
Request parameters:
  • company_webhook_id (optional | integer) filter for webhook requests by webhook ID
  • action (optional | string) filter for webhook requests by action
  • response_code (optional | integer) filter for webhook requests by response code received
  • posted_after (optional | datetime): filter for webhook requests posted after this time
  • posted_before (optional | datetime): filter for webhook requests posted before this time
  • per_page (optional | integer): no of records to return in response. default is 25
  • page_no (optional | integer): page no for the records list. default is 1
Example Requests:
GET /company_webhook_requests
curl -H "X-Api-Key: 12345" "https://api.keeptruckin.com/v1/company_webhook_requests?response_code=400"
Response Status:
  • 200
Response Body:
  • Success message
Sample JSON Request:
GET /company_webhook_requests.json
Sample JSON Response:
{
  "company_webhook_requests": [
    {
      "company_webhook_request": {
        "id": 9,
        "company_webhook_id": 9,
        "action": "vehicle_location_updated",
        "url": "https://keeptruckin.com/callbacktest/b8271c",
        "secret": "75cac802b19050fa83fcffaddebab5bf",
        "format": "json",
        "payload": {
          "action": "vehicle_location_updated"
        },
        "response_code": null,
        "num_failures": 3,
        "posted_at": "2016-02-17T14:00:00Z"
      }
    },
    {
      "company_webhook_request": {
        "id": 8,
        "company_webhook_id": 8,
        "action": "vehicle_location_received",
        "url": "https://keeptruckin.com/callbacktest/6d4b6b",
        "secret": "51e07b1a7995bd9cd98f8569230d78ac",
        "format": "json",
        "payload": {
          "action": "vehicle_location_received"
        },
        "response_code": null,
        "num_failures": 4,
        "posted_at": "2016-02-16T14:00:00Z"
      }
    },
    {
      "company_webhook_request": {
        "id": 7,
        "company_webhook_id": 7,
        "action": "vehicle_location_updated",
        "url": "https://keeptruckin.com/callbacktest/5d9853",
        "secret": "a5d235965722c14ba163cbd618e7cdb6",
        "format": "json",
        "payload": {
          "action": "vehicle_location_updated"
        },
        "response_code": null,
        "num_failures": 5,
        "posted_at": "2016-02-15T14:00:00Z"
      }
    }
  ],
  "pagination": {
    "per_page": 25,
    "page_no": 1,
    "total": 3
  }
}
Sample XML Request:
GET /company_webhook_requests.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <company_webhook_requests>
    <company_webhook_request>
      <id>9</id>
      <company_webhook_id>9</company_webhook_id>
      <action>vehicle_location_updated</action>
      <url>https://keeptruckin.com/callbacktest/b8271c</url>
      <secret>75cac802b19050fa83fcffaddebab5bf</secret>
      <format>json</format>
      <payload>
        <action>vehicle_location_updated</action>
      </payload>
      <response_code nil="true"/>
      <num_failures>3</num_failures>
      <posted_at>2016-02-17T14:00:00Z</posted_at>
    </company_webhook_request>
    <company_webhook_request>
      <id>8</id>
      <company_webhook_id>8</company_webhook_id>
      <action>vehicle_location_received</action>
      <url>https://keeptruckin.com/callbacktest/6d4b6b</url>
      <secret>51e07b1a7995bd9cd98f8569230d78ac</secret>
      <format>json</format>
      <payload>
        <action>vehicle_location_received</action>
      </payload>
      <response_code nil="true"/>
      <num_failures>4</num_failures>
      <posted_at>2016-02-16T14:00:00Z</posted_at>
    </company_webhook_request>
    <company_webhook_request>
      <id>7</id>
      <company_webhook_id>7</company_webhook_id>
      <action>vehicle_location_updated</action>
      <url>https://keeptruckin.com/callbacktest/5d9853</url>
      <secret>a5d235965722c14ba163cbd618e7cdb6</secret>
      <format>json</format>
      <payload>
        <action>vehicle_location_updated</action>
      </payload>
      <response_code nil="true"/>
      <num_failures>5</num_failures>
      <posted_at>2016-02-15T14:00:00Z</posted_at>
    </company_webhook_request>
  </company_webhook_requests>
  <pagination>
    <per_page>25</per_page>
    <page_no>1</page_no>
    <total>3</total>
  </pagination>
</data>

7) Retry Webhook Requests

Request format:
POST /company_webhook_requests/retry
Request parameters:
  • ids (required | array of integers) the webhook request IDs to retry
Example Requests:
POST /company_webhook_requests
curl -X POST -H "X-Api-Key: 12345" -d "ids[]=123" "https://api.keeptruckin.com/v1/company_webhook_requests/retry
Response Status:
  • 200
Response Body:
  • Success message
Sample JSON Request:
POST /company_webhook_requests.json
Sample JSON Response:
{
  "success": true
}
Sample XML Request:
POST /company_webhook_requests.xml
Sample XML Response:
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <success>true</success>
</data>