Trial Balance API
Getting Started
TrueTrack, previously known as "BRP RISE," is a profitability diagnosis and improvement program and tool for dealers. The TrueTrack program aims to help dealers improve their financial performance by measuring their results and providing benchmarks with similar dealerships in their region.
TrueTrack provides:
- Dashboards, trend analysis, and detailed reporting for each department.
- Customizable dealership benchmarking composite.
- Support staff who help improve the TrueTrack program aims and value of dealership data.
TrueTrack provides the following benefits to dealership employees:
- Reduces the time it takes to dig through dealership data to show what matters.
- Monitors each department without requiring complex spreadsheets or tables.
- Easily benchmarks each department against a variety of detailed competitive averages.
- Quickly highlights the most significant profit opportunities within each department.
- Diagnoses each profit opportunity to help build an improvement plan with managers.
More information can be found on the TrueTrack site.
The Trial Balance API allows your DMS to send selected financial information from a dealer to the TrueTrack program.
❗❗ The Trial Balance API is NOT developed by BRP but by the TrueTrack partner, Jackson Dawson ❗❗
The API documentation is provided in the DCP portal for easy access, but Jackson Dawson (JD) develops, certifies, and supports it.
Business Summary
Topic | Description |
|---|---|
Scope | Global API for all regions |
Main functionalities |
|
Business processes supported | |
Benefits for dealers |
|
Benefits for BRP |
|
Technical Information
Characteristics
API Type | DSP Type | DCP Version | Complexity |
|---|---|---|---|
Get data from BRP | DMS | V3 - International | Low |
Send data to BRP | CRM | V4 - North America | A bit more |
Transaction with BRP | | | Somewhat more |
Authentication
The API is using OAuth 2.0 authentication.
To get your credentials, you have to write to support@truetracksolution.com.
You need a valid access token before calling this API or you must call the TrueTrack Authentication endpoint to get one.
The access token is valid for 60 minutes! (3600 seconds)
Base Authentication URL
Test | https://qa-api-auth.truetracktest.com |
|---|---|
Production | https://api-auth.truetracksolution.com |
Base URL
Test | https://qa-api.truetracktest.com |
|---|---|
Production | https://api.truetracktest.com |
Resource: Trial Balance Data
A DMS uses the Trial Balance Data resource to send the dealer's financial data for the TrueTrack program.
JSON Representation
{
"dealer_no": "0000123456",
"generated_at": "2023-10-25T17:10:43+00:00",
"first_year_month_available": "2017-01",
"fiscal_year_start_month": 1,
"currency": "USD",
"language": "en",
"manual_report": true,
"user": "cj",
"general_ledger": {
"accounts_hash": "4aed7e591448f28faa89c475edc5b5bb",
"accounts": [
{
"number": "16000",
"description": "Parts & Accessories Inventory",
"category": "asset",
"debit": true
},
{
"number": "22300",
"description": "Loans",
"category": "liability",
"debit": false
},
{
"number": "30000-07",
"description": "Owners Equity",
"category": "equity",
"debit": false
},
{
"number": "44320",
"description": "Sales New BRP PWC",
"category": "revenue",
"debit": false
},
{
"number": "54320",
"description": "Cogs New BRP PWC",
"category": "cost of sales",
"debit": true
},
{
"number": "70000",
"description": "Advertising BRP",
"category": "expense",
"debit": true
}
]
},
"trial_balances": [
{
"year_month": "2023-03",
"accounts_hash": "c60be469e4c79fb36c3daead049d6a2d",
"accounts": [
{
"number": "16000",
"beginning_balance": 1927737.66,
"ending_balance": 1933336.42,
"count": 47119
},
{
"number": "44320",
"beginning_balance": -135044.82,
"ending_balance": -378856.22,
"count": 7
},
{
"number": "54320",
"beginning_balance": 119516.00,
"ending_balance": 338556.00
},
{
"number": "70000",
"beginning_balance": 13271.50,
"ending_balance": 13455.38
}
]
},
{
"year_month": "2023-04",
"accounts_hash": "5dbe84a4f973145a7e7c1e1e61c9173b",
"accounts": [
{
"number": "16000",
"beginning_balance": 1933336.42,
"ending_balance": 1932254.80,
"count": 47165
},
{
"number": "44320",
"beginning_balance": -378856.22,
"ending_balance": -476483.01,
"count": 3
},
{
"number": "54320",
"beginning_balance": 338556.00,
"ending_balance": 426507.00
},
{
"number": "70000",
"beginning_balance": 13455.38,
"ending_balance": 14845.38
}
]
}
]
}Properties
All the number fields with decimals use the dot(.) as the decimal separator. The coma (,) is NOT supported as a decimal separator.
Property | Type | Definition | Notes |
|---|---|---|---|
dealer_no * | string | Dealer number. | Length: 10 |
generated_at * | string | Date/Time the data is generated, in ISO 8601. | Format: yyyy-mm-ddThh:mm:ssZ or yyyy-mm-ddThh:mm:ss+000 |
first_year_month_available * | string | Earliest available month of data. | Format: yyyy-mm Example: “2016-01” |
fiscal_year_start_month * | number | The month that the fiscal year starts. | Format: 1 to 12 |
currency * | string | The currency in which the balance is provided. The available values are listed in the Currency table below. | Length: 3 |
language * | string | Language of account descriptions. See the Languages table below. | Length: 2 |
manual_report * | boolean | True when manually generated by a user, false if generated by the automatic job. | |
user * | string | User identification. Empty string if an automatic job does the submittal. | Max Length: 64 |
general_ledger * | object | Contains the list of accounts found in the general ledger |
|
general_ledger.accounts_hash * | string | The hash of the general ledger accounts array. | Length: 32 |
general_ledger.accounts | List of objects | |
|
general_ledger.accounts. number * | string | The account number. It can't be empty. | Length: 1 to 64 |
general_ledger.accounts. description * | string | A description of the account. It can't be empty. | Length: 1 to 256 |
general_ledger.accounts. category * | string | Enum of account category, one of:
| |
general_ledger.accounts.debit | boolean | True if the account is for debit, false if it's for credit. |
|
trial_balances * | List of objects | |
|
trial_balances.year_month * | string | The month of the trial balance. | Format: yyyy-mm Example: “2023-01” |
trial_balances.accounts_hash * | string | The hash of the trial balance accounts array. | Length: 32 |
trial_balances.accounts * | List of objects | An array of trial balance accounts for the month. |
|
trial_balances.accounts.number * | string | The account number. | Length: 64 |
trial_balances.accounts. beginning_balance * | number | The balance amount at the start of the month. For all profit & loss accounts, the value is 0 for the first month of the fiscal year. | ±99999999.99 |
trial_balances.accounts. ending_balance * | number | The balance amount at the end of the month. | ±99999999.99 |
trial_balances.accounts.count | number | Optional: An associated count based on the type of account. | ±99999999.99 |
Properties in blue and marked with an asterisk (*) are mandatory in the resource.
Currency
Sales Organisation | Currency |
|---|---|
1010 | CAD |
3020 | USD |
Languages
Code | Language |
|---|---|
de | German |
en | English |
es | Spanish |
fi | Finnish |
fr | French |
it | Italian |
nl | Dutch |
no | Norwegian |
pt | Portuguese (Brazil) |
sv | Swedish |
Limitations & Constraints
Number Format
All the number fields with decimals use the dot(.) as the decimal separator. The coma (,) is NOT supported as a decimal separator.
Understanding Trial Balance
Payload Structure
Each submitted payload contains two large objects:
- The list of accounts from the general ledger.
- A list of trial balances, one per submitted month.
General Ledger
Every submission contains the full listing of general ledger accounts, regardless of whether the account has a balance in the trial balances submitted.
In some systems, general ledger accounts are marked “inactive”. These accounts must also be included if the account has a balance in any month.
👉 Only general ledger accounts where transactions are recorded, often referred to as detailed accounts, are sent.
The other accounts, like header, consolidated, total, summary, etc., are NOT sent.
Trial Balances
Each submission can include multiple months of trial balances. Each trial balance month contains every account with a balance at the beginning or end of the month.
👉 Accounts with a zero balance at the start and end of the month should not be included.
In any trial balance submitted, a positive number means that the account has a debit balance, and a negative number means that the account has a credit balance, regardless of what the "normal" balance is for that account.
Many accounting systems reset the balances in profit and loss accounts at the start of a new fiscal year. The beginning_balance property for all profit and loss accounts in the first month of the fiscal year must be 0.
Hashes
The accounts_hash property in the general_ledger and trial_balances objects determine if accounts have changed since the last submission.
The TrueTrack backend saves the accounts_hash value received in the payload. TrueTrack compares the saved accounts_hash value with the received accounts_hash value when receiving a payload. If they are the same, there were no changes, and the data doesn't need to be processed.
👉All properties of the accounts must be included in the hash.
For the general ledger, the hash is calculated on the following properties of all the accounts:
- number
- description
- category
- debit
For trial balances, the hash is calculated on the following properties of all the accounts:
- number
- beginning_balance
- ending_balance
- count
The hash value must be 32 characters long and is calculated using the MD5 algorithm.
The exact way you calculate the hash is unimportant as long as all the properties are included.
TrueTrack will not try to recalculate the hash 😁
The hash could be calculated directly on the JSON payload before sending it.
For example, the hash could be calculated on the accounts array before sending the payload.
The hash can also be calculated on the fly while creating the payload.
Quality Service (QS) Counts
The goal of the BRP Quality Service (QS) program is to improve a dealer's service operation, increase revenue and profits, and offer a better overall customer experience.
A dealer in the Quality Service program must provide service and PA&A counts to get the full benefit of the metrics generated in TrueTrack.
The count property in the trial balance account data provides information based on the account usage.
Entry in TrueTrack
It's possible that your DMS doesn't provide a way for the dealer to capture the counts. If so, the dealer can enter the counts directly on the TrueTrack site.
The counts can be entered under Data Tools > Import Data by clicking the Quick Entry for Counts & Miscellaneous button in the upper right corner. The dealer selects the correct month and year and submits the counts. The data was sent via the Trial Balance API if your count fields are greyed out.
Service Department Counts
Depending on how the dealer's accounting system tracks revenue in the service department, the dealer may have more or fewer counts to enter than the sample shown below.
In this example, the dealer entered the number of repair orders (ROs) for the Customer Paid Labor, Internal Labor, Sublet Repair, and Warranty Labor accounts. As a rule, the total of those lines will equal the total number of repair orders (ROs) in the department for the month.
Some dealerships assign a specified amount of shop supplies to each repair order or perhaps to repair orders over a set dollar amount. For example, less than half of the dealership’s ROs had shop supply costs allocated.
Number of Employees
TrueTrack asks for the number of employees based on how a dealership breaks out the payroll costs. Ideally, a dealership tracks the service department payroll separately for Service Manager(s), Service Writer(s), Service Technician(s), and all other Service Support Staff, as shown in the sample below.
PA&A Department
Some dealerships track PA&A in separate general ledger accounts, and some combine the categories. In the sample shown below, the dealership includes Apparel and Accessories sales with Parts sales.
Counts Summary
Account Usage | Count |
|---|---|
BRP ATV sales | Number of units sold |
COS | No count required |
Expense | No count required |
F&I sales | Number of invoices sold during the month |
Inventory | Number of vehicles in inventory at the end of the month |
Parts sales | Number of invoices sold during the month |
RO sales | Number of invoices sold during the month |
API Reference
curl --location 'https://api-auth.truetracksolution.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: XSRF-TOKEN=5a01ec89-9085-437e-a7a8-d0dac11779b4' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
--data-urlencode 'scope=trial_balance/write' \
--data-urlencode 'grant_type=client_credentials'curl --location 'https://api.truetracksolution.com/trial-balance' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
--data '{
"dealer_no": "0000123456",
"generated_at": "2023-10-25T17:10:43+00:00",
"first_year_month_available": "2017-01",
"fiscal_year_start_month": 1,
"currency": "USD",
"language": "en",
"manual_report": true,
"user": "cj",
"general_ledger": {
"accounts_hash": "4aed7e591448f28faa89c475edc5b5bb",
"accounts": [
{
"number": "16000",
"description": "Inventory Parts & Accessories",
"category": "asset",
"debit": true
},
{
"number": "22300",
"description": "Loans from Shareholders",
"category": "liability",
"debit": false
},
{
"number": "30000-07",
"description": "Owners Equity",
"category": "equity",
"debit": false
},
{
"number": "44320",
"description": "Sales New BRP SSV",
"category": "revenue",
"debit": false
},
{
"number": "54320",
"description": "Cogs New BRP SSV",
"category": "cost of sales",
"debit": true
},
{
"number": "70000-05",
"description": "Advertising BRP",
"category": "expense",
"debit": true
}
]
},
"trial_balances": [
{
"year_month": "2023-03",
"accounts_hash": "c60be469e4c79fb36c3daead049d6a2d",
"accounts": [
{
"number": "16000",
"beginning_balance": 1927737.66,
"ending_balance": 1933336.42,
"count": 47119
},
{
"number": "44320",
"beginning_balance": -135044.82,
"ending_balance": -378856.22,
"count": 7
},
{
"number": "54320",
"beginning_balance": 119516.00,
"ending_balance": 338556.00
},
{
"number": "70000-05",
"beginning_balance": 13271.50,
"ending_balance": 13455.38
}
]
},
{
"year_month": "2023-04",
"accounts_hash": "5dbe84a4f973145a7e7c1e1e61c9173b",
"accounts": [
{
"number": "16000",
"beginning_balance": 1933336.42,
"ending_balance": 1932254.80,
"count": 47165
},
{
"number": "44320",
"beginning_balance": -378856.22,
"ending_balance": -476483.01,
"count": 3
},
{
"number": "54320",
"beginning_balance": 338556.00,
"ending_balance": 426507.00
},
{
"number": "70000-05",
"beginning_balance": 13455.38,
"ending_balance": 14845.38
}
]
}
]
}
'How To
This section provides information on how to obtain specific results with the API.
Get an Access Token
Get an access token to call the Trial Balance API.
curl --location 'https://api-auth.truetracksolution.com/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=REPLACE_ME_CLIENT_ID' \
--data-urlencode 'client_secret=REPLACE_ME_CLIENT_SECRET' \
--data-urlencode 'scope=trial_balance/write' \
--data-urlencode 'grant_type=client_credentials'Upload Trial Balance Data
Send the dealer's trial balance data for a month.
curl --location 'https://api.truetracksolution.com' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"dealer_no": "0000123456",
"generated_at": "2023-10-25T17:10:43+00:00",
"first_year_month_available": "2017-01",
"fiscal_year_start_month": 1,
"currency": "USD",
"language": "en",
"manual_report": true,
"user": "cj",
"general_ledger": {
"accounts_hash": "4aed7e591448f28faa89c475edc5b5bb",
"accounts": [
{
"number": "16000",
"description": "Inventory Parts & Accessories",
"category": "asset",
"debit": true
},
{
"number": "22300",
"description": "Loans from Shareholders",
"category": "liability",
"debit": false
},
{
"number": "30000-07",
"description": "Owners Equity",
"category": "equity",
"debit": false
},
{
"number": "44320",
"description": "Sales New BRP SSV",
"category": "revenue",
"debit": false
},
{
"number": "54320",
"description": "Cogs New BRP SSV",
"category": "cost of sales",
"debit": true
},
{
"number": "70000-05",
"description": "Advertising BRP",
"category": "expense",
"debit": true
}
]
},
"trial_balances": [
{
"year_month": "2023-03",
"accounts_hash": "c60be469e4c79fb36c3daead049d6a2d",
"accounts": [
{
"number": "16000",
"beginning_balance": 1927737.66,
"ending_balance": 1933336.42,
"count": 47119
},
{
"number": "44320",
"beginning_balance": -135044.82,
"ending_balance": -378856.22,
"count": 7
},
{
"number": "54320",
"beginning_balance": 119516.00,
"ending_balance": 338556.00
},
{
"number": "70000-05",
"beginning_balance": 13271.50,
"ending_balance": 13455.38
}
]
}
]
}
'Error Handling
This section presents various scenarios of improper or wrong calls, which result in error messages and improper results.
400 Bad Request
The 400 status code is generally seen during development and integration and should not be received during normal operations. The returned response contains the information needed to correct the problem.
Many problems can cause a 400 status code; the most common ones are listed in the table below.
Response | Resolution |
|---|---|
Returned if the dealer number is invalid. {
"status": "400",
"id": "rrt-07cdd77f98c381924-d-ea-22529-1513654-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "String \"22391888\" is too short (length: 8, required minimum: 10): []"
}
]
}
}
} | If the dealer is using your DMS, it may be that they are not a BRP dealer anymore. Check with them and disable parts inventory updates. Make sure that the dealer number is 10 characters. If you are saving the dealer number without leading '0', add the leading '0' before calling the API. The error is also returned if the dealer is not an active BRP dealer. |
Returned if a property is missing. {
"status": "400",
"id": "e090fc8d-1651-42d9-9008-4c1bcb666212",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "Invalid request body: [object has missing required properties ([\"fiscal_year_start_month\"])]"
}
} | Add the missing property to the payload. |
Returned if a date has an invalid format. {
"status": "400",
"id": "0829c7e5-f568-4a04-9c71-0977937d5586",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "Invalid request body: [format attribute \"int32\" not supported, string \"2023-10-25T17:10:43\" is invalid against requested date format(s) [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.SSSZ]]"
}
} | Change the date string format to match the payload format. |
Returned if a number has an invalid format.
{
"status": "400",
"id": "fa8fced3-020a-46d5-a2e0-da93bfd9b6c5",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "Invalid request body: [instance failed to match all required schemas (matched only 0 out of 1), format attribute \"int32\" not supported]"
}
}
| All the amounts in the payload have a format of ±9999999.99. Change the property format to match the payload. |
401 Unauthorized
The 401 Unauthorized error status code is returned when you try to call the Trial Balance API with an expired access_token.
You have to get a new access_token with a call to the Trial Balance Authentication endpoint.
The 401 Unauthorized error status code is also returned if you didn't request access to the API by sending an email to [email protected].
DSP Requirements
Functional Requirements
ID | Type | Requirement |
|---|---|---|
1 | Mandatory | The dealer must be able to manually submit trial balance data. |
2 | Mandatory | The dealer must be able to manually submit the trial balance data for a month as many times as desired. |
3 | Mandatory | The dealer has the following options to submit the trial balance data:
|
4 | Mandatory | The DMS must set the user property to an identifier of the person making the manual submission, preferably the email address. |
5 | Mandatory | The beginning_balance property for all profit & loss accounts must be 0 for the first month of the fiscal year. |
6 | Mandatory | If available, 5 years of historical data must be submitted when the dealer joins the TrueTrack program. |
7 | Optional | The dealer must be able to activate automatic uploads of trial balance data. |
8 | Optional | When the automatic upload is active, the trial balance data must be sent using the following schedule:
|
Certification Activities
This section presents all the certification activities and validations that must be completed to certify the API.
Validations
The tests listed in the table below must be successfully done in the test environment before you can start the dealer pilot phase.
👉 In all the tests, you have to provide a report listing the accounts and the trial balance data. The report will be used to validate the received trial balance data.
The report can be provided in PDF, Excel, or CSV.
For all tests, the following validations are done:
- All accounts are included, even if they have no balance.
- Compare balances versus exported trial balance (spreadsheet, PDF, etc..)
- The first month of the fiscal year
- The last month of the fiscal year
- Month in the middle
ID | Test | Expected Result |
|---|---|---|
1 | Manually submit the trial balance data for the current month. | The submitted data is valid. |
2 | Manually submit the trial balance data for all months for an entire calendar year. | The submitted data is valid. Validate that the general ledger accounts_hash property has NOT changed. |
3 | Manually submit the trial balance data for all months of the current fiscal year. | The submitted data is valid. |
4 | Manually submit the trial balance data for all months of the previous fiscal year. | The submitted data is valid. |
5 | Change an account description and submit the trial balance data for the current month. | The submitted data is valid. Validate that the general ledger accounts_hash property has changed. |
6 | Change some account balances If automatic submission is implemented, | The submitted data is valid. Validate that the trial balance accounts_hash property has changed. |
7 | If an automatic submission is implemented, run the jobs long enough to perform the daily and weekly submittals. | The submitted data is valid. The manual_report property is false. |
Dealer Pilot
The table below describes the dealer pilot parameters and validations.
Parameter | Value |
|---|---|
Environment | Production |
Number of dealers | 1 to 3 |
Duration | 3 weeks |
Validation 1 | If manual submittal is used, the dealer must submit its trial balance data at least every 2 days for the duration of the dealer pilot phase. |
Validation 2 | If automatic submittal is used, the trial balance data must be submitted daily for the dealer pilot phase. |
Postman
This section describes what is available in Postman to explore the API.
Environments
A Postman environment is available to try the Trial Balance API. This Postman environment contains variables used by the queries and is configured to connect to the test environment.
Collections
The DMS - Trial Balance collection contains examples of calls to the API to upload trial balance data.