Fortellis API Guide — Which API to Use and When
This guide gives you a clear, practical breakdown of the Fortellis APIs we rely on, and when to use each. It’s built so your team can move fast, avoid guesswork, and know exactly which integration path fits the data you need.
1. Authentication — Read the Official Fortellis Docs
Fortellis authentication is handled through their OAuth service.
Instead of listing raw token URLs, refer directly to the Fortellis documentation:
👉 Fortellis Authentication Documentation
Look for the OAuth / Authentication section relevant to your integration.
Why this matters:
Every Fortellis API call requires a valid Bearer token. The authentication docs walk through how to request, refresh, and use tokens properly.
2. FI Sales APIs
These APIs provide FI (Finance & Insurance) vehicle sale records from CDK Drive. Use the API that matches your data needs based on history, state, and frequency of updates.
FI Sales History Setup — Historical (>31 Days Old)
Retrieves FI Sales data older than 31 days.
Use when:
- Initial integration setup
- Deep data backfills
- Reporting on long-term FI sales behavior
🔗 Docs:
https://apidocs.fortellis.io/apis/638f1179-e2bf-4aac-b601-a9acc51247f8
FI Sales Bulk — Full Dataset Within Date Range
Returns all FI Sales records matching your date window.
Use when:
- Daily/weekly ETL
- Full dataset retrieval
- When statuses (C, B, P, F, I, U) are required
🔗 Docs:
https://apidocs.fortellis.io/apis/b54ba111-7874-4c25-b8d9-ba3b3eb722ef
FI Sales Delta — Recently Closed or Updated Only
Returns incremental updates, ideal for reducing payload size.
Use when:
- Syncing frequently
- You only need the latest changes
- Optimizing for performance over volume
🔗 Docs:
https://apidocs.fortellis.io/apis/b54ba111-7874-4c25-b8d9-ba3b3eb722ef
3. Repair Order APIs
APIs for pulling Repair Order (RO) data from CDK Drive.
Repair Order History Setup — Historical (>31 Days Old)
Retrieves historical RO data beyond the 31-day boundary.
Use when:
- Backfilling large datasets
- First-time integration setup
🔗 Docs:
https://apidocs.fortellis.io/apis/48e7060a-b828-4de5-8505-76fd9e21b3c0
Repair Order Bulk — Open + Recently Closed ROs
Returns all open and recently closed ROs.
Use when:
- Ongoing service operations analytics
- Daily shop-operations syncs
🔗 Docs:
https://apidocs.fortellis.io/apis/cf3e1079-e617-4e4d-acd0-21e991f60408
Repair Order Delta — Recently Closed Only
Returns incremental updates for recently closed ROs.
Use when:
- Running tight, efficient updates
- Avoiding bulky full pulls
🔗 Docs:
https://apidocs.fortellis.io/apis/cf3e1079-e617-4e4d-acd0-21e991f60408
4. Customer API
Customer Bulk — Full Customer Records Retrieval
Returns all customers asynchronously via operationId.
Use when:
- CRM or CDP integration
- Customer lifecycle analytics
- Full customer exports
🔗 Docs:
https://apidocs.fortellis.io/apis/f83a79c6-8cf9-4c1a-b45e-b266634eaf90
5. Long-Running Operations — How Fortellis Handles Big Jobs
Most Fortellis APIs follow a predictable three-step pattern:
1. Start the request
You get back an operationId.
2. Poll the status endpoint
Keep checking until the job is finished.
3. Pull the result
Once complete, retrieve your dataset.
Your implementation already handles logging, polling, and the date-window logic. Fortellis simply expects you to follow this async flow.
6. Quick Decision Table — Which API Should You Use?
Need | Correct API | Type |
Backfill FI Sales older than 31 days (max 7 years 31 days back) | FI Sales Setup | fi-sales-setup |
Full FI Sales set for a date range | FI Sales Bulk | fi-sales-bulk |
Only recent FI Sales changes | FI Sales Delta | fi-sales-delta |
Backfill Repair Orders older than 31 days | RO Setup | repair-order-setup |
All open + recently closed ROs | RO Bulk | repair-order-bulk |
Only recent closed ROs | RO Delta | repair-order-delta |
Full customer dataset | Customer Bulk | customer |
7. Fortellis Documentation Index
Here are all relevant docs in one place:
- FI Sales History Setup
- Repair Order History Setup
- Customer Retrieval
- FI Sales Bulk & Delta
- Repair Order Bulk & Delta
https://apidocs.fortellis.io/apis/638f1179-e2bf-4aac-b601-a9acc51247f8
https://apidocs.fortellis.io/apis/48e7060a-b828-4de5-8505-76fd9e21b3c0
https://apidocs.fortellis.io/apis/f83a79c6-8cf9-4c1a-b45e-b266634eaf90
https://apidocs.fortellis.io/apis/b54ba111-7874-4c25-b8d9-ba3b3eb722ef
https://apidocs.fortellis.io/apis/cf3e1079-e617-4e4d-acd0-21e991f60408
8. BettrData Implementation
To process Foretellis data files for a new dealership, follow these steps:
1. Pull Subscription ID and Department ID
- Run the GetBearerToken API call and copy the returned access_token
- Open the Subscriptions API call and paste the access_token into the Auth token section and run the call
- The results from this call provide all possible Departments for each Dealership
- To find the Subscription ID, search for the dealership in the orgName field. Right above the orgName you will find the subscriptionID for that dealership.
- The Department IDs are also located in this object under the apiDmsInfo list.
- For example, if you needed the Department ID for historical sales you would search for "name": "CDK Drive History Setup FI Sales” and then copy the id in the departments list.
2. Copy Existing Fortellis Integration
- Head to the Integrations tab within BettrData and search for Paramus Hyundai.
- Duplicate the integration you are wanting to setup for a new Dealership
- Assign to the new dealership and check the box to keep integration parameters.
- Find the duplicated integration under the new dealership and open the details for the integration. Replace the Subscription and Department ID with IDs you copied earlier.
3. Pull the Data
Within the integration, click Run Now and choose your date boundaries.
The historical data has a date limit of 7 years and 31 days from the current date. The integration will not fail if the date is selected pass this range but the API will attempt to pull for every month past the date and thus will take more time to complete the API call.