Blue Ink Tech API

Less Paperwork, More Driving


Unsplashed background img 1

API Docs

Making a Call

BIT offers a RESTful API that only sends its responses back in JSON format. Currently, we only support GET, POST, and PUT call types. The address for these calls are made in the format found below. The first is when a resource is called in general, with option of more specific parameters being applied from there, and the second is there when you're looking for a specific driver or vehicle.

https://blueinktech.com/api/v1/<resource>
https://blueinktech.com/api/v1/<resource>/<id>

Each call must contain the x-api-key header along with the API key generated by the user for authentication purposes. The next section covers obtaining a key.

Authenticating

For directions on how to generate and manage your API keys in our new web portal, click here. For directions on how to manage your keys on the legacy portal, see below.

To make any calls using the BIT API, you'll need to generate an API key to use. This can be done by going to the "My Account" page in the web portal. Once there, click "Request API Key" in the "My API Keys" section of the page. You'll be presented with two sets of options: the carrier that will be using the key, and the second is the type of permissions the key will have (Read-Only or Read/Write). Once you've selected these options, you can click the key to copy it, or click on its type to change its permissions.

When a key is generated, all actions taken while using that key will be performed as if the user that generated the key had performed them. A key can only act within the carrier it was generated for, and may not be used to perform actions for other carriers even if the user generating the key is an admin for those carriers. A carrier is currently allowed up to 200 requests an hour across all keys. If the user that generated a key is removed as an admin for the carrier that the key was generated for, the key will no longer work.

Standard Parameters

The following parameters are standard to nearly every GET call that is made.

Name Type Description
page int This is used for the purposes of pagination. It defaults to 1 if nothing is supplied.
per_page int This is used for the purposes of pagination. It defaults to 25 if nothing is supplied.
timezone string This is used when a call receives or outputs a date/time. The default time that is used is UTC. The following are a list of valid time zones.
  • US/Eastern
  • US/Pacific
  • US/Samoa
  • US/Hawaii
  • US/Alaska
  • US/Central
  • US/Mountain
  • Canada/Atlantic
  • Pacific/Guam
  • US/Arizona
GET Users

This returns a list of users for the carrier. Below are the addresses to access it and a list of parameters that can be supplied. The <id> in the address may be replaced with the id of a specific user.

https://blueinktech.com/api/v1/users/
https://blueinktech.com/api/v1/users/<id>

Name Type Description
duty_status string Search for users with this as their last duty status. Valid duty statuses are:
  • off_duty
  • on_duty
  • sleeper
  • driving
  • yard_move
  • personal_use
user_role string Search for a user of this role. Valid roles are:
  • admin
  • driver
  • user
Example Response
GET Vehicles

This returns a list of vehicles for the carrier. Below are the addresses to access it and a list of parameters that can be supplied. The <id> in the address may be replaced with the id of a specific vehicle.

https://blueinktech.com/api/v1/vehicles/
https://blueinktech.com/api/v1/vehicles/<id>

Name Type Description
driver_ids string Search for vehicles by its last driver. This is a comma delimited list of driver ids.
Example Response
GET Inspections

This returns a list of DVIRs for the carrier. Please note that a date range is required.

https://blueinktech.com/api/v1/inspections

Name Type Description
start_date required
date (YYYY-MM-DD)		 Date start
end_date required
date (YYYY-MM-DD)		 Date end
driver_ids string A comma delimited list of driver ids that have performed inspections.
vehicle_ids string A comma delimited list of vehicle ids that have had inspections performed on them.
status string Show inspections with or without defects. If no status is specified, vehicles with both defects and no defects will be returned. Valid inputs are:
  • with_defects
  • no_defects
Example Response
GET Logs

This returns a list of a driver's logs. Below are the addresses to access it and a list of parameters that can be supplied. Please note that a date range and driver id are required.

https://blueinktech.com/api/v1/logs

Name Type Description
start_date required
date (YYYY-MM-DD)		 Date start
end_date required
date (YYYY-MM-DD)		 Date end
driver_id required
int		 Search for logs with this driver's user id.
Example Response
GET Vehicle Locations

This returns a list of current locations for vehicles. The <id> in the address may be replaced with the id of a specific vehicle. That vehicle must either have a subscription to Fleet Visibility or BIT Full Service.

https://blueinktech.com/api/v1/vehicle_locations/
https://blueinktech.com/api/v1/vehicle_locations/<id>

Example Response
GET Vehicle Route

This returns a list of places that the specified vehicle has been over the given time frame. The <id> in the address may be replaced with the id of a specific vehicle. That vehicle must either have a subscription to Fleet Visibility or BIT Full Service. Please note that a date range no larger than one week, and a vehicle id are required.

https://blueinktech.com/api/v1/vehicle_route/
https://blueinktech.com/api/v1/vehicle_route/<id>

Name Type Description
start_date required
date (YYYY-MM-DD)		 Date start
end_date required
date (YYYY-MM-DD)		 Date end
vehicle_id required
int		 Search for a route with the vehicle's id.
Example Response
GET Driver Locations

This returns a list of current driver locations. The vehicle that the driver was driving must either have a subscription to Fleet Visibility or BIT Full Service. Below is the address to access it and a list of parameters that can be supplied.

https://blueinktech.com/api/v1/driver_locations

Name Type Description
driver_ids string A list of comma delimited driver ids used for getting their current location.
Example Response
GET Contacts

This returns of contacts for the carrier. These contacts can be listed as contacts for job legs by their ID

https://blueinktech.com/api/v1/job_details

Name Type Description
id int The ID of the contact you're looking for.
first_name string Contacts with this as their first name.
last_name string Contacts with this as their last name.
email string Contacts with this as their email.
Example Response
GET Job Details

This returns a full list of jobs, their legs, weight, and cargo for the specified date range.

https://blueinktech.com/api/v1/job_details

Name Type Description
job_number string The name given to the job
start_date required
date (YYYY-MM-DD)		 Start date range for the jobs that are listed
end_date required
date (YYYY-MM-DD)		 End date range for the jobs that are listed
Example Response
POST User

This starts the creation of a new user and sends an invite to the email address that's listed to finish account creation. The response returns the newly created user id.

https://blueinktech.com/api/v1/users

Name Type Description
email required
string		 The user's email. This will be the address the invitation will be sent to as well as their login.
first_name required
string		 The user's first name.
last_name required
string		 The user's last name.
role required
string		 The role the user will occupy. The following is a list of valid values.
  • administrator
  • driver
Example Response
POST Vehicle

This creates a new vehicle. The response that is returned is the newly created vehicle

https://blueinktech.com/api/v1/vehicles

Name Type Description
number required
string		 This is the name of the vehicle that will be created.
vin required
string		 The VIN of the vehicle.
Example Response
POST Contact

This creates a contact for use with the jobs API. The response will be the ID of the newly created contact.

https://blueinktech.com/api/v1/users

Name Type Description
first_name required
string		 First name of the contact
last_name required
string		 Last name of the contact
email string The email of the contact
phone string The phone number of the contact
cell_phone string The cell phone number of the contact
Example Response
POST Job

This creates a new job, job legs, and cargo. Jobs must be uniuqely named within the carrier, but a job can be updated. The response is the ID of the newly created job.

https://blueinktech.com/api/v1/vehicles

Name Type Description
name required
string		 The name of the job
notes string Notes regarding the main job
legs[] required
array		 You must have at least two legs when creating a job. You must specify an index for the job leg the information you're supplying relates to.
legs[0][driver_id] int The driver responsible for driving this leg
legs[0][codriver_id] int The codriver responsible for driving this leg
legs[0][vehicle_id] int The id of the vehicle that is responsible for driving this leg.
legs[0][scheduled_start_time] date/time (YYYY-MM-DD HH:MM:SS) The time this leg of the job is supposed to start.
legs[0][scheduled_end_time] date/time (YYYY-MM-DD HH:MM:SS) The time this leg of the job is supposed to end.
legs[0][notes] string Notes regarding this leg of the job.
legs[0][scheduled_drive_time_min] int The amount of drive time there is for this leg of the job. If you don't supply drive time, it will be calculated for you based on leg start/end times
legs[0][scheduled_distance_mi] int The number of miles that are supposed to be traveled for this leg of the job.
legs[0][start_geofence_id] required
int		 The ID of the geofence that the leg starts from. You can supply either this or the name of the geofence. If you supply both, only the ID will be used.
legs[0][start_geofence_name] required
string		 The name of the geofence that the leg starts from. You can supply either this or the ID of the geofence. If you supply both, only the ID will be used.
legs[0][end_geofence_id] required
int		 The ID of the geofence that the leg ends at. You can supply either this or the name of the geofence. If you supply both, only the ID will be used.
legs[0][end_geofence_name] required
string		 The name of the geofence that the leg ends at. You can supply either this or the ID of the geofence. If you supply both, only the ID will be used.
legs[0][start_contact_id] int ID of the contact for the start of the leg
legs[0][end_contact_id] int ID of the contact for the end of the leg
legs[0][scheduled_weight_lb] decimal Expected leg weight in pounds
legs[0][trailers][trailer_1_id] int ID of the first trailer that will be used for this job leg.
legs[0][trailers][trailer_2_id] int ID of the second trailer that will be used for this job leg.
legs[0][trailers][trailer_3_id] int ID of the third trailer that will be used for this job leg.
legs[0][cargo][] array An array of cargo for the leg.
legs[0][cargo][0][handling_unit] string The name of the unit the cargo is provided in (pallets, boxes, etc)
legs[0][cargo][0][quantity] int The number of the unit being provided
legs[0][cargo][0][stackable] boolean Is this cargo stackable?
legs[0][cargo][0][hazardous] boolean Is this cargo hazardous?
legs[0][cargo][0][length_in] decimal Length of the cargo in inches
legs[0][cargo][0][width_in] decimal Width of the cargo in inches
legs[0][cargo][0][height_in] decimal Height of the cargo in inches
legs[0][cargo][0][scheduled_weight_lb] decimal Weight of the cargo in pounds.
Example Response
PUT Vehicle

This updates a vehicles name. Names are unique within each carrier.

https://blueinktech.com/api/v1/vehicles

Name Type Description
id required
int		 The id of the vehicle to be updated.
number string The new name of the vehicle
Example Response
PUT Job

This updates an existing job. You must supply all of the information about the job when updating it including job legs, and cargo. You may supply the jobs existing ID and a new name for the job, or the existing jobs name to be updated. The paramters to update a job are exactly the same as those to create one. The response is the ID of the updated job.

https://blueinktech.com/api/v1/vehicles

Name Type Description
id required
string		 The ID of the job. You may supply this and the job name, or just the job name
name required
string		 The name of the job
notes string Notes regarding the main job
legs[] required
array		 You must have at least two legs when creating a job. You must specify an index for the job leg the information you're supplying relates to.
legs[0][driver_id] int The driver responsible for driving this leg
legs[0][codriver_id] int The codriver responsible for driving this leg
legs[0][vehicle_id] int The id of the vehicle that is responsible for driving this leg.
legs[0][scheduled_start_time] date/time (YYYY-MM-DD HH:MM:SS) The time this leg of the job is supposed to start.
legs[0][scheduled_end_time] date/time (YYYY-MM-DD HH:MM:SS) The time this leg of the job is supposed to end.
legs[0][notes] string Notes regarding this leg of the job.
legs[0][scheduled_drive_time_min] int The amount of drive time there is for this leg of the job. If you don't supply drive time, it will be calculated for you based on leg start/end times
legs[0][scheduled_distance_mi] int The number of miles that are supposed to be traveled for this leg of the job.
legs[0][start_geofence_id] required
int		 The ID of the geofence that the leg starts from. You can supply either this or the name of the geofence. If you supply both, only the ID will be used.
legs[0][start_geofence_name] required
string		 The name of the geofence that the leg starts from. You can supply either this or the ID of the geofence. If you supply both, only the ID will be used.
legs[0][end_geofence_id] required
int		 The ID of the geofence that the leg ends at. You can supply either this or the name of the geofence. If you supply both, only the ID will be used.
legs[0][end_geofence_name] required
string		 The name of the geofence that the leg ends at. You can supply either this or the ID of the geofence. If you supply both, only the ID will be used.
legs[0][start_contact_id] int ID of the contact for the start of the leg
legs[0][end_contact_id] int ID of the contact for the end of the leg
legs[0][scheduled_weight_lb] decimal Expected leg weight in pounds
legs[0][trailers][trailer_1_id] int ID of the first trailer that will be used for this job leg.
legs[0][trailers][trailer_2_id] int ID of the second trailer that will be used for this job leg.
legs[0][trailers][trailer_3_id] int ID of the third trailer that will be used for this job leg.
legs[0][cargo][] array An array of cargo for the leg.
legs[0][cargo][0][handling_unit] string The name of the unit the cargo is provided in (pallets, boxes, etc)
legs[0][cargo][0][quantity] int The number of the unit being provided
legs[0][cargo][0][stackable] boolean Is this cargo stackable?
legs[0][cargo][0][hazardous] boolean Is this cargo hazardous?
legs[0][cargo][0][length_in] decimal Length of the cargo in inches
legs[0][cargo][0][width_in] decimal Width of the cargo in inches
legs[0][cargo][0][height_in] decimal Height of the cargo in inches
legs[0][cargo][0][scheduled_weight_lb] decimal Weight of the cargo in pounds.
Example Response