Overview

Welcome to the ClearRoad API documentation!

ClearRoad is a SaaS platform that enables to quickly build a road pricing solution.

ClearRoad API is a synchronisation protocol that ensures 100% accuracy, auditability, transparency on the data and the financial transactions managed by the platform. ClearRoad work as a central ledger from which other systems can feed into or pull data from.

The API is based on the synchronization of messages. The document below describes the different messages and the data that compose them. ClearRoad Platform will process each message and provide a status on each of the message in the platform. If the platform approves the messages, then it will create or update the necessary documents (or objects) in the system. This documentation provides the details of the different documents (or objects) that can be created.

You will find here samples to send and receive data on the API, and will be able to test them with a basic account or your own account.

Using the Playground

You can use the ClearRoad API in the following cases:

you want to manage user accounts: follow the Account Manager documentation
you want to report mileage for user vehicles: follow the Data Provider documentation

Please refer to the API Reference for more information on how to use the JavaScript SDK.

Tutorial

Account Manager: before starting the tutorial, you can either follow the Data Provider tutorial to send road usage data or send an email to ClearRoad so that we can create transactions for you.

Account Manager

Registering a road account

To create road account registration for a specific vehicle:

cr.post({
  "account_manager": "testamref",
  "data_collector": "testmpref",
  "condition": "test-stc-1",
  "cert_id": "1051",
  "account_reference": "USER000011",
  "effective_date": "2018-04-01T00:00:00Z",
  "expiration_date": "2018-04-01T00:00:00Z",
  "fuel_consumption": "12.0",
  "fuel_taxable": "1",
  "obu_reference": "977298026d50a5b1795c6563",
  "vehicle_reference": "2C1MR2295T6789740",
  "product_line": "ruc_metrics",
  "portal_type": "Road Account Message"
});

You can get the status of your request of road account registration by listing them:

cr.allDocs({
  query: 'portal_type: "Road Account Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'grouping_reference'
  ]
});

This method allows to create a road account registration for a vehicle associate with a specific road account. If the road account does not exist, the system will create a new road account as well.

ClearRoad will only accept and process road usage data for a specific vehicle if the vehicle has already an active road account registration.

cr.post({account_manager, data_collector, condition, cert_id, account_reference, effective_date, expiration_date, fuel_consumption, fuel_taxable, obu_reference, vehicle_reference, product_line, portal_type});

Parameters

Property	Description	Required	Default
account_manager	The reference of an account manager that already exists in ClearRoad Platform.	No
data_collector	The reference should be of a data provider that already exists in ClearRoad Platform.	Yes
condition	Sale Trade Condition to apply. The reference should be of an object that already exists in ClearRoad Platform.	Yes
cert_id	The DOT certificate ID value	Yes
account_reference	The reference of the road account to be defined.	Yes
effective_date	The start date of the customer account. Could not be left empty. Should be in UTC.	Yes
expiration_date	The stop date of the customer account. Could be left empty - the road account will have no expiration date. Should be in UTC.	No
fuel_consumption	Combined EPA Miles Per Gallon (MPG) rating for the vehicle.	Yes
fuel_taxable	Boolean defining if customer is subject to taxable fuel.	Yes
obu_reference	An object for this on board unit will be created in the ClearRoad platform if it is nor already present.	No
vehicle_reference	An onject for this vehicle will be created in the ClearRoad Platform if it is not already present.	Yes
product_line	The reporting method the customer choosed to use. Values: `odometer_message_no_transaction` `odometer_message_transaction` `ruc_metrics` `service`	Yes
portal_type	The type of the message in the ClearRoad Platform. Only one value is possible.	Yes	Road Account Message

Try it out

Listing road accounts

You can list the road accounts along their messages:

cr.allDocs({
  query: 'portal_type: "Road Account"',
  select_list: [
    'reference',
    'registrations'
  ]
}).push(result => {
  result.data.rows.forEach(row => {
    // reference is used as "destination_reference" when registering a road account
    const reference = row.value.reference;
    // contains the documents associated with the account
    const registrations = row.value.registrations;
  });
});

List the road accounts you have access to.

cr.allDocs({query, select_list})

Parameters

Property	Value
query	`'portal_type: "Road Account"'`
select_list	Any of `'reference'`: road account reference `'registrations'`: all documents linked to the road account

Try it out

Registering a billing period

Adding a billing period can be done using the following post method:

cr.post({
  "reference": "2018Q1",
  "start_date": "2018-04-01T00:00:00Z",
  "stop_date": "2018-04-01T00:00:00Z",
  "portal_type": "Billing Period Message"
});

You can get the status of your request of billing period message by listing them:

cr.allDocs({
  query: 'portal_type: "Billing Period Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'destination_reference',
    'grouping_reference'
  ]
});

For applications that only need the aggregate charges over a long period of time, it is easier to set up billing periods. ClearRoad will aggregate for you the related transactions in reports.

To learn more about reports, see the report section.

cr.post({reference, start_date, stop_date, portal_type});

Parameters

Property	Description	Required	Default
reference	The reference given to the new billing period which will be used to reference it in the future.	Yes
start_date	The date, starting which, the billing period is going to be active. Should be in UTC.	Yes
stop_date	The date, starting which, the billing period will become inactive. Should be UTC. If it is left empty, the billing period will never turn inactive, once activated.	Yes
portal_type	The type of message in the ClearRoad Platform. Only one value is possible	Yes	Billing Period Message

Try it out

Listing road events

You can list the road events using:

cr.allDocs({
  query: 'portal_type: "Road Event"',
  select_list: [
    'source_reference',
    'vehicle_reference',
    'obu_reference',
    'event_date',
    'report_date',
    'type',
    'state'
  ]
});

List processed road messages.

cr.allDocs({query, select_list})

Parameters

Property	Value
query	`'portal_type: "Road Event"'`
select_list	Any of `'source_reference'`: the `reference` of the source road message `'vehicle_reference'`: the VIN of the vehicle `'obu_reference'`: the OBU of the vehicle `'event_date'`: date associated with the road message `'report_date'`: the date the message was sent `'type'`: the event type `'state'`: state of the road message (`acknowledged` if the message was processed)

Try it out

Listing road transactions

You can list the road transactions using:

cr.allDocs({
  query: 'portal_type: "Road Transaction"',
  select_list: [
    'vehicle_reference',
    'obu_reference',
    'transaction_date',
    'report_date',
    'state',
    'transaction_type',
    'rule',
    'fuel_quantity',
    'miles_quantity'
  ]
});

List road transactions.

cr.allDocs({query, select_list})

Parameters

Property Value

query 'portal_type: "Road Transaction"'

select_list Any of
'vehicle_reference': the VIN of the vehicle
'obu_reference': the OBU of the vehicle
'transaction_date': the date that the miles being reported were traveled on
'report_date': the date when the transaction was reported
'transaction_type': a value to indicate the type of message from the MRD
'rule': see rules
'fuel_quantity': amount of fuel consumed at the transaction date (gallon)
'miles_quantity': miles traveled at the transaction date
'state': state of the transaction (acknowledged if it was processed)

Property	Value
query	`'portal_type: "Road Transaction"'`
select_list	Any of `'vehicle_reference'`: the VIN of the vehicle `'obu_reference'`: the OBU of the vehicle `'transaction_date'`: the date that the miles being reported were traveled on `'report_date'`: the date when the transaction was reported `'transaction_type'`: a value to indicate the type of message from the MRD `'rule'`: see rules `'fuel_quantity'`: amount of fuel consumed at the transaction date (gallon) `'miles_quantity'`: miles traveled at the transaction date `'state'`: state of the transaction (`acknowledged` if it was processed)

Try it out

Requesting a report

Step 1: request a report:

cr.post({
  "report_type": "AccountBalance",
  "billing_period_reference": "2018Q1",
  "request_date": "2017-07-18T00:00:00Z",
  "request": "",
  "portal_type": "Road Report Request"
}).push(reference => {
  // use this reference in step 2
});

Step 1.1: if you need to find the reference of your request, use:

cr.allDocs({
  query: 'grouping_reference: "data" AND portal_type: "Road Report Request" AND billing_period_reference: "<reference>"',
  select_list: [
    'source_reference',
    'request_date'
  ]
}).push(result => {
  // look for the result matching your request from step 1
  result.data.rows.forEach(row => {
    // use this reference in step 2
    const reference = row.value.source_reference;
  });
});

Step 2: check the status of the request:

cr.allDocs({
  query: 'grouping_reference: "report" AND portal_type: "Road Report Request" AND source_reference: "<reference from step 1>"',
  select_list: [
    'state',
    'comment'
  ]
}).push(result => {
  const document = result.data.rows[0].value;
  if (document.state === 'processed') {
    // report is ready, go to step 3
  }
  else {
    // check again later (processing time depends on collected data)
  }
});

Step 3: get the result of the report using the source_reference obtained at step 1 (or find it with step 1.1):

cr.getReportFromRequest('reference').push(report => {
  // display the report
  console.log(JSON.Stringify(report));
});

You can request a report that will be processed in the background and will be available later on. This is done in 3 steps as per the code sample.

cr.post({report_type, billing_period_reference, request_date, request, portal_type});

Parameters

Property	Description	Required	Default
report_type	The type of the requested report. Values: `AccountBalance`	Yes
billing_period_reference	The reference of the billing period. The billing period should already exist in the ClearRoad Platform.	Yes
request_date	The datetime for which the request is made. Should be in UTC.	Yes
request	Used to give specific parameters to report if needed. This filed could be left empty for an AccountBalance report.	No
portal_type	The type of the object in the ClearRoad Platform. Only one possible value.	Yes	Road Report Request

Try it out

Data Provider

Sending road usage data

Sending road usage data can be done using the following post method:

cr.post({
  "request": {
    "description": "Mileage data",
    "vehicle_reference": "1GTG6BE38F1262119",
    "obu_reference": "977298026d50a5b1795c6563",
    "type": "MRP",
    "transaction_date": "2018-04-01T00:00:00Z",
    "mileage_details": {
      "fuel_price": "-0.30000001192092896",
      "fuel_quantity": "0.14000000059604645",
      "miles_price": "0.014999999664723873",
      "miles_quantity": "3.700000047683716",
      "rule_id": "41",
      "sub_rule_id": "1"
    }
  },
  "portal_type": "Road Message"
});

You can get the status of your request of road messages by listing them:

cr.allDocs({
  query: 'portal_type: "Road Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'destination_reference',
    'grouping_reference'
  ]
});

You can send the usage of mileage of a user using Road Message.

cr.post({request, portal_type});

Parameters

Property	Description	Required	Default
request.description	The description of the reported mileage	Yes
request.vehicle_reference	The Vehicle Identification Number of the vehicle for which the message is reported.	Yes
request.obu_reference	The On Board Unit reference of the device for which the message is reported	Yes
request.type	A value to indicate the type of message. Values: `ADJ` `CRE` `FEE` `INV` `MRP`	Yes
request.transaction_date	The date at which mileage was traveled. Should be in UTC.	Yes
request.mileage_details[].fuel_price	The price of the fuel consumed at the transaction date.	No	0
request.mileage_details[].fuel_quantity	The quantity of fuel consumed at the transaction date.	Yes	0
request.mileage_details[].miles_price	The price of miles traveled.	No	0
request.mileage_details[].miles_quantity	The number of miles traveled.	Yes	0
request.mileage_details[].rule_id	An identifier associated with a geographic area, or zone, in which a specific rate per mile will be assessed for miles traveled. FIPS codes are used to identify states.	Yes	0
request.mileage_details[].sub_rule_id	0 if the travel was on public roads, 1 if it was on private roads	Yes	0
portal_type	The type of message in the ClearRoad Platform. Only one type possible	Yes	Road Message

Try it out

Reporting a road event

Reporting events can be done using the following post method:

cr.post({
  "request": {
    "vehicle_reference": "1GTG6BE38F1262119",
    "obu_reference": "977298026d50a5b1795c6563",
    "event_details": {
      "type": "12",
      "date": "2018-04-01T00:00:00Z"
    }
  },
  "portal_type": "Road Event Message"
});

You can get the status of your request of road event messages by listing them:

cr.allDocs({
  query: 'portal_type: "Road Event Message"',
  select_list: [
    'source_reference',
    'state',
    'comment',
    'destination_reference',
    'grouping_reference'
  ]
});

Events like connection of device, or management event like missing mileage can be reported through the usage of Road Event Message.

cr.post({request, portal_type});

Parameters

Property	Description	Required	Default
request.vehicle_reference	The Vehicle Identification Number of the road account registration for which the event is reported	Yes
request.obu_reference	The On Board Unit reference of the road account registration for which the event is reported	Yes
request.event_details[].type	The ID of the event. Every type has it own ID.	Yes
request.event_details[].date	The datetime of the event. Should be a UTC time.	Yes
portal_type	The type of the object in ClearRoad Platform. Only one value is possible.	Yes	Road Event Message

Try it out

Listing road events

You can list the road events using:

cr.allDocs({
  query: 'portal_type: "Road Event"',
  select_list: [
    'source_reference',
    'vehicle_reference',
    'obu_reference',
    'event_date',
    'report_date',
    'type',
    'state'
  ]
});

List processed road messages.

cr.allDocs({query, select_list})

Parameters

Property	Value
query	`'portal_type: "Road Event"'`
select_list	Any of `'source_reference'`: the `reference` of the source road message `'vehicle_reference'`: the VIN of the vehicle `'obu_reference'`: the OBU of the vehicle `'event_date'`: date associated with the road message `'report_date'`: the date the message was sent `'type'`: the event type `'state'`: state of the road message (`acknowledged` if the message was processed)

Try it out

Please refer to the Account Manager's Listing road events section.

Listing road transactions

You can list the road transactions using:

cr.allDocs({
  query: 'portal_type: "Road Transaction"',
  select_list: [
    'vehicle_reference',
    'obu_reference',
    'transaction_date',
    'report_date',
    'state',
    'transaction_type',
    'rule',
    'fuel_quantity',
    'miles_quantity'
  ]
});

List road transactions.

cr.allDocs({query, select_list})

Parameters

Property Value

query 'portal_type: "Road Transaction"'

Property	Value
query	`'portal_type: "Road Transaction"'`
select_list	Any of `'vehicle_reference'`: the VIN of the vehicle `'obu_reference'`: the OBU of the vehicle `'transaction_date'`: the date that the miles being reported were traveled on `'report_date'`: the date when the transaction was reported `'transaction_type'`: a value to indicate the type of message from the MRD `'rule'`: see rules `'fuel_quantity'`: amount of fuel consumed at the transaction date (gallon) `'miles_quantity'`: miles traveled at the transaction date `'state'`: state of the transaction (`acknowledged` if it was processed)

Try it out

Please refer to the Account Manager's Listing road transactions section.

Miscellaneous

MRD types

Code	Description
ADJ	Adjusted mileage transaction
CRE	Credit transaction
FEE	Fees transaction
INV	Invoicing transaction
MRP	Reported mileage transaction

Event types

Common MRD Health code for OBD-II devices:

Code	Type
EVENT_AM_100	AM Event for No mileage received from VIN for given date
EVENT_AM_101	AM Event for Unreadable message from MRD / Checksum failure
EVENT_AM_102	AM Event for MessageIDs from MRD not correctly incrementing
EVENT_AM_103	AM Event for VIN - MRD ID mismatch
EVENT_AM_104	AM Event for Date/time not increasing from last message
EVENT_AM_105	AM Event for Accumulated mileage decreased from last message
EVENT_AM_106	AM Event for New total mileage does not equal sum of mileage in zones
EVENT_AM_107	AM Event for InvalidRule ID
EVENT_AM_108	AM Event for Unreasonable miles per day
EVENT_MRD_1	MRD Event for Low Voltage
EVENT_MRD_10	MRD Event for Software updates
EVENT_MRD_11	MRD Event for Degraded mileage data
EVENT_MRD_12	MRD Event for Missed mileage
EVENT_MRD_13	MRD Event for Vendor-specific
EVENT_MRD_2	MRD Event for Compromising Anomaly
EVENT_MRD_3	MRD Event for Storage full
EVENT_MRD_4	MRD Event for Disconnects / reconnects
EVENT_MRD_5	MRD Event for Connected to new vehicle
EVENT_MRD_6	MRD Event for Vehicle interface communications failure
EVENT_MRD_7	MRD Event for Location data degraded
EVENT_MRD_8	MRD Event for Incorrect date/time
EVENT_MRD_9	MRD Event for Software resets

Mileage Rule ids

Code	Description
0	UNDIFFERENTIATED
1	ALABAMA
2	ALASKA
4	ARIZONA
5	ARKANSAS
6	CALIFORNIA
8	COLORADO
9	CONNECTICUT
10	DELAWARE
11	DISTRICT OF COLUMBIA
12	FLORIDA
13	GEORGIA
15	HAWAII
16	IDAHO
17	ILLINOIS
18	INDIANA
19	IOWA
20	KANSAS
21	KENTUCKY
22	LOUISIANA
23	MAINE
24	MARYLAND
25	MASSACHUSETTS
26	MICHIGAN
27	MINNESOTA
28	MISSISSIPPI
29	MISSOURI
30	MONTANA
300	CANADA
301	Mexico
302	International Miles
303	Canada - Alberta
304	Canada - British Columbia
305	Canada - New Brunswick
306	Canada - Newfoundland and Labrador
307	Canada - Nova Scotia
308	Canada - Manitoba
309	Canada - Ontario
31	NEBRASKA
310	Canada - Quebec
311	Canada - Prince Edward Island
312	Canada - Saskatchewan
313	Canada - Northwest Territories
314	Canada - Nunavut
315	Canada - Yukon
32	NEVADA
320	Mexico - Aguascalientes
321	Mexico - Baja California
322	Mexico- Baja California Sur
323	Mexico - Campeche
324	Mexico - Chiapas
325	Mexico - Chihuahua
326	Mexico - Coahuila
327	Mexico - Colima
328	Mexico - Durango
329	Mexico - Guanajuato
33	NEW HAMPSHIRE
330	Mexico - Guerrero
331	Mexico - Hidalgo
332	Mexico - Jalisco
333	México - Mexico
334	Mexico - Michoacán
335	Mexico - Morelos
336	Mexico - Nayarit
337	Mexico - Nuevo León
338	Mexico - Oaxaca
339	Mexico - Puebla
34	NEW JERSEY
340	Mexico - Queretaro
341	Mexico - Quintana Roo
342	Mexico - San Luis Potosí
343	Mexico - Sinaloa
344	Mexico - Sonora
345	Mexico - Tabasco
346	Mexico - Tamaulipas
347	Mexico - Tlaxcala
348	Mexico - Veracruz
349	Mexico - Yucatán
35	NEW MEXICO
350	Mexico - Zacatecas
351	Mexico - Mexico City
36	NEW YORK
37	NORTH CAROLINA
38	NORTH DAKOTA
39	OHIO
40	OKLAHOMA
41	OREGON
42	PENNSYLVANIA
44	RHODE ISLAND
45	SOUTH CAROLINA
46	SOUTH DAKOTA
47	TENNESSEE
48	TEXAS
49	UTAH
50	VERMONT
51	VIRGINIA
53	WASHINGTON
54	WEST VIRGINIA
55	WISCONSIN
56	WYOMING
60	AMERICAN SAMOA
66	GUAM
72	PUERTO RICO
78	VIRGIN ISLANDS

Mileage Sub-Rule ids

Code	Description
1	General roads
2	Private roads

Terminology

We list here all terms involved in CleaRoad API.

Account manager

Account manager is the entity that manage the RUC Payers accounts and the collection of the RUC (Road User Charging) from the RUC Payers.

Road charger

Road charger is the entity that owns and/or operate the road. The road charge is the final recipient of the RUC. The road chargers could be states, cities, municipalities as well as private companies.

RUC payer

The RUC payer is in charge of paying the RUC to the account manager for its usage of road owned by the road charger. The road charger has defined who are the RUC payer usually through rules and regulations. The account manager needs to report to the clearinghouse which RUC payers he has under its management. The RUC payer can be an individual or an organisation.

ClearRoad Platform

ClearRoad Platform or the clearinghouse is the centralized financial platforms that hosts the global ledger(s) for different account managers, data collectors and road chargers. Road Account is the account that keeps a balance of all the RUC transactions associated with a vehicle registration.

Properties and messages

Billing Period

An object that defines the time period that an invoice covers. The billing period is defined by the account manager for the RUC Payers he is managing.

Billing Period Message

A message sent by an account manager to the ClearRoad Platform to create a new billing period or update an existing one in the CR Platform.

Currency

A system of money used by an account manager for the billing of RUC Payers. Example of a currency: USD, Euro.

On Board Unit (OBU)

An object that represents an external or internal device that collects the driving data of a vehicle. In the case of an external device, it is usually inserted in the standard diagnostics port of the vehicle. The data collected by an OBU is used to compute the RUC and record different road events. An OBU is represented in the ClearRoad Platform by a unique alphanumeric identifier.

Odometer Message

A message sent by the data collector to the ClearRoad Platform to indicate the odometer reading of a specific vehicle, for a specific moment of time. It is used in the case of the RUC is not computed from the data collected by the RUC Payer's OBU.

Odometer Reading

An object that contains information on the odometer of a vehicle and the exact timestamp when this reading was observed.

Organisation

An object that represents an organisation in the ClearRoad Platform that interacts with it. Examples of organisations: data collectors, account managers, public bodies etc.

Person

An object that represents a physical person of an organisation related to ClearRoad Platform and that has an account in the ClearRoad system.

Road Account Message

An message sent by an account manager to ClearRoad Platform that defines transaction validation parameters to allocate a road usage data to a specific road account. This message could be also used to define necessary objects like OBU and vehicle.

Road Account Registration

An object that indicates the registration of the pair OBU and vehicle by a Road Account.

Road Event

An object that indicates an anomaly or an important event to a vehicle or an on board unit (like plugging/unplugging an on board unit in a vehicle, detection of mileage abnormalities etc). Usually detected by the On Board Unit. Road Events include also the anomalies of data collection reporting, detected by the ClearRoad Platform.

Road Account

An object that identifies the RUC Payer and his road account registrations.

Road Mileage Message

A message that contains mileage data and events for a road account for some period of time. The road mileage messages are generated by the on board units. This message could be replaced by a combination of Road Message and Road Event Messages.

Road Event Message

A message that is used in the case of the Road Mileage Message is not used. It contains information about events related to a vehicle or an on board unit.

Road Message

A message that is used in the case if the Road Mileage Message is not used. It contains mileage data for some period of time.

Road Report Request

A request of RUC balances sent by an account manager to ClearRoad Platform. The time period for which the request is made is bound by the validity time of the billing period referenced in the request.

Road Transaction

An object that describes the charges for the road usage, depending of the service used. It is generated by Road Messages (in the production ClearRoad Platform, it is generated by the Road Mileage Message).

Sale Trade Condition

An object that contains a pricing list for all services.

Service

An object that represents a service provided by ClearRoad. A service is a right to drive on specific roads, using a predefined road taxation for them.

Vehicle

A physical vehicle that is identified in the system by its Vehicle Identification Number (VIN).