Skip to main content

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.

EndpointDate limits
bulkstartDate at most 31 days before the request
historystartDate at most 7 years before the request
historyendDate more than 31 days before the request
historyAt 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 URLCalls per minuteCalls counted across
https://api.fortellis.io/cdk/drive/fisales/v3120Not stated by Fortellis
https://api.fortellis.io/cdk/drive/fisalessetup/v375The 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:

HeaderValue
AuthorizationBearer <access token>
Subscription-IdThe dealer's Fortellis subscription
Department-IdThe dealer's CDK department
Request-IdA UUID, the same for every request of one operation

Asynchronous operations​

Neither endpoint returns deals directly. Each request starts an operation:

  1. The submit GET returns an operationId and a status link, <base URL>/long-operations/<operationId>/status.
  2. 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 a message.
  3. The result link, <base URL>/long-operations/<operationId>/result, returns {"data": [...]}, one element per deal.

Response structure​

Each deal has six sections:

SectionContents
dealDeal number and type, sale type, dates (contractDate, creationDate, accountingDate, salesDate), prices, finance and lease terms, buy and sell rates, gross profit, lien holder
vehiclevin, make, model, year, age, stock number, mileage, cost
crmCommission, sales-credit and spiff totals, plus one sub-object per sales role
incentivesDealer incentive, program, rebate amount, and a commonRebateDetails array of {id, amount, code, description}
totalsDeal-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
tradesA 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 varSecrets Manager nameContents
FORTELLIS_CLIENT_IDdagster/mercedes/fortellis-client-idOAuth2 client ID
FORTELLIS_CLIENT_SECRETdagster/mercedes/fortellis-client-secretOAuth2 client secret
FORTELLIS_FI_DEALER_SUBSCRIPTIONSdagster/mercedes/fortellis-fi-dealer-subscriptionsJSON 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.