Mercedes Fortellis F&I Sales Source
Fortellis is CDK's API platform. Its CDK Drive F&I sales API returns a dealer's F&I sales deals. A request identifies the dealer by its Fortellis subscription and its CDK department.
Endpoints
GET https://api.fortellis.io/cdk/drive/fisales/v3/bulk?startDate=<YYYY-MM-DD>T00:00:00[&endDate=<YYYY-MM-DD>T00:00:00]
GET https://api.fortellis.io/cdk/drive/fisalessetup/v3/history?startDate=<YYYY-MM-DD>T00:00:00&endDate=<YYYY-MM-DD>T00:00:00
Both endpoints return the deals from startDate to endDate. endDate must be on
or after startDate. The bulk endpoint's endDate is optional and defaults to the
current date. Each date may include a time of day, as yyyy-mm-ddThh:mm:ss. The path
segment after the host (cdk) is the Fortellis environment.
| Endpoint | Date limits |
|---|---|
| bulk | startDate at most 31 days before the request |
| history | startDate at most 7 years before the request |
| history | endDate more than 31 days before the request |
| history | At most 183 days from startDate to endDate |
The history endpoint rejects a range longer than 183 days with the message "Date range
exceeds limit of 183 days". It rejects an endDate within the last 31 days with
400 Bad Request.
Fortellis refreshes both endpoints' data every 60 minutes.
Rate limits
Each limit applies to every endpoint under its base URL, including the operation status and result endpoints.
| Base URL | Calls per minute | Calls counted across |
|---|---|---|
https://api.fortellis.io/cdk/drive/fisales/v3 | 120 | Not stated by Fortellis |
https://api.fortellis.io/cdk/drive/fisalessetup/v3 | 75 | The whole application |
Authentication
Authentication is OAuth2 client credentials against
https://identity.fortellis.io/oauth2/aus1p1ixy7YL8cMq02p7/v1/token, with scope
anonymous. The client ID and secret are sent as HTTP Basic auth. Every API
request also has these headers:
| Header | Value |
|---|---|
Authorization | Bearer <access token> |
Subscription-Id | The dealer's Fortellis subscription |
Department-Id | The dealer's CDK department |
Request-Id | A UUID, the same for every request of one operation |
Asynchronous operations
Neither endpoint returns deals directly. Each request starts an operation:
- The submit
GETreturns anoperationIdand a status link,<base URL>/long-operations/<operationId>/status. - The status link returns the operation's
status. The status response of a completed operation also contains a result link. The status response of a failed operation contains amessage. - The result link,
<base URL>/long-operations/<operationId>/result, returns{"data": [...]}, one element per deal.
Response structure
Each deal has six sections:
| Section | Contents |
|---|---|
deal | Deal number and type, sale type, dates (contractDate, creationDate, accountingDate, salesDate), prices, finance and lease terms, buy and sell rates, gross profit, lien holder |
vehicle | vin, make, model, year, age, stock number, mileage, cost |
crm | Commission, sales-credit and spiff totals, plus one sub-object per sales role |
incentives | Dealer incentive, program, rebate amount, and a commonRebateDetails array of {id, amount, code, description} |
totals | Deal-level totals: totalGross, totalDown, tax, totalTaxRate, totalTaxableFees, totalCommission, totalOfMonthlyPayments, totalInsurancePremiums, totalFinancedFeeOptions, totalOptionsFees, totalInitFees, totalAnnFees, totalBasePrice, totalCapReduction, totalCashSurplus, totalDMVLicenseFeeCalifornia, totalFrontCostAdjustments, totalBackCostAdjustments, weOweCostTotal, weOweSaleTotal, and the trade totals totalTradeAllowance, totalTradesACV, totalTradesNet, totalTradesOver, totalTradesPayoff |
trades | A tradeDetails array with one object per trade-in vehicle, plus tradeDealerDefined1 through tradeDealerDefined8 |
Each tradeDetails element describes one trade-in: tradeVIN, tradeStock,
tradeYear, tradeMake, tradeMakeName, tradeModel, tradeModelName,
tradeModelNo, tradeModelType, tradeStyle, tradeColor and tradeMileage, plus
the amounts tradeACV, tradeGross, tradeOver, tradePayOff and netTrade.
Secrets
| Env var | Secrets Manager name | Contents |
|---|---|---|
FORTELLIS_CLIENT_ID | dagster/mercedes/fortellis-client-id | OAuth2 client ID |
FORTELLIS_CLIENT_SECRET | dagster/mercedes/fortellis-client-secret | OAuth2 client secret |
FORTELLIS_FI_DEALER_SUBSCRIPTIONS | dagster/mercedes/fortellis-fi-dealer-subscriptions | JSON list of {dealerId, organizationId, subscriptionId, departmentId}, one per dealer |
The secrets are declared in deployments/aws/terraform/solutions/secrets/secrets.tf
with no value. Their values are set by hand after the secrets solution is
applied. projects/ai_mercedes/container_context.yaml points each env var at its
secret through a <NAME>_SECRET_ID variable. For local development, export the
env vars directly.