DecisioQ Auto Auction Developer Integration Manual

How software developers should incorporate DecisioQ into auction, remarketing, dealer, lender, fleet, and logistics platforms

Version 1.0 | Generated June 25, 2026

Contents

1. Executive summary

2. Integration architecture

3. Auto Auction decision use cases

4. API authentication and endpoint workflow

5. Data mapping rules

6. Implementation recipes

7. Payload examples

8. UI and workflow integration

9. Production readiness checklist

10. Appendix: template catalog

1. Executive summary

DecisioQ is a decision-analysis API that ranks alternatives using weighted criteria, constraints, and algorithms such as TOPSIS or WSM. In an Auto Auction environment, it should be used when a system needs an explainable recommendation among competing vehicles, buyers, sellers, vendors, lanes, reserve prices, or liquidation actions.

The integration pattern is simple: collect candidate options from the auction platform, enrich each option with normalized business measurements, send the options to DecisioQ with an Auto Auction template or custom criteria, receive ranked results and explanations, then store and display the decision trace alongside the auction transaction.

2. Integration architecture

Layer	What it does	Auto Auction examples
Source systems	Own the operational data and workflow state.	Auction run list, vehicle inventory, condition reports, seller history, buyer accounts, transport quotes, market demand feeds.
Integration service	Transforms auction data into a DecisioQ DecisionRequest.	Maps VIN/lot/CR data into option scores; applies site-specific thresholds; chooses template.
DecisioQ API	Scores options, applies constraints, ranks results, explains outcome, and returns trace.	/api/v1/decide, /api/v1/decision/sensitivity, /api/v1/decision/scenario.
Application UI	Presents recommendation, confidence, exclusions, and explanation to users.	Buyer dashboard, lane manager, reserve pricing screen, seller scorecard, transportation dispatch.
Audit store	Persists request, response, user action, and final override.	Decision audit table linked to VIN, lot number, sale ID, buyer ID, seller ID, or transport order.

Recommended request flow

1. Authenticate with /api/v1/token and cache the bearer token until expiry.
2. Retrieve /api/v1/templates during startup or periodically so template names and criteria can be validated.
3. Build a DecisionRequest from auction-domain data. Each option must include an OptionId and scores for every criterion used by the template or custom request.
4. Call /api/v1/decide for the recommendation. Use RunSensitivity=true where decision stability matters.
5. Persist the complete request and response, including excluded options, warnings, confidence, explanation, and trace.
6. Display the top recommendation and allow users to accept, override, or rerun with changed assumptions.

3. Auto Auction decision use cases

Use case	Primary users	When to call DecisioQ	Typical factors
Vehicle Acquisition	Buyer, acquisition desk, or fleet intake	Rank vehicles to purchase from external auctions or seller feeds.	Expected profit, demand, condition, purchase price, transport cost, days to sell.
Bid Optimization	Online/live auction bidding module	Recommend bid ceiling or target lot among candidates.	Expected ROI, bid amount, demand, risk, condition.
Lane Scheduling	Auction operations manager	Prioritize which lane/time block should receive vehicle groups.	Revenue, buyer interest, volume, operational complexity.
Reserve Price Setting	Seller services or pricing team	Choose reserve policy that balances sale probability and proceeds.	Expected sale price, sale probability, inventory age, competition.
Seller Selection	Commercial accounts team	Score consignors, fleet sellers, and dealer partners.	Vehicle quality, sell-through, profit, dispute rate, volume.
Buyer Qualification	Registration, compliance, credit, or floorplan workflow	Rank or approve buyers using payment and dispute history.	Purchase history, payment reliability, credit score, dispute history.
Vehicle Grading	Condition report or inspection application	Produce consistent grading support from inspection metrics.	Mechanical, exterior, interior, accident history, mileage, title status.
Inventory Liquidation	Dealer/fleet remarketing operations	Prioritize aging units for liquidation or aggressive pricing.	Inventory age, holding cost, sale price, demand, transport cost.
Transportation Vendor Selection	Post-sale operations and dispatch	Select carrier based on cost, speed, damage history, capacity, reliability.	Transportation cost, delivery time, damage rate, capacity, reliability.

4. API authentication and endpoint workflow

Endpoint	Method	Purpose	Use in Auto Auction systems
/health	GET	Checks service availability.	Use in platform health checks and deployment monitoring.
/api/v1/token	POST	Exchanges clientId/clientSecret for a JWT bearer token.	Called by the auction integration service, not directly from browser clients.
/api/v1/templates	GET	Returns available templates and default criteria.	Cache available Auto Auctions templates and validate UI configuration.
/api/v1/ahp/generate	POST	Generates weights from pairwise comparisons.	Use when business users tune criteria through preference comparisons.
/api/v1/decide	POST	Main ranking and recommendation endpoint.	Use for vehicle, buyer, seller, lane, reserve, and transport decisions.
/api/v1/decision/sensitivity	POST	Measures how stable the recommendation is under weight variation.	Use before automated bidding, reserve changes, or high-value acquisition decisions.
/api/v1/decision/scenario	POST	Compares baseline and hypothetical decisions.	Use for what-if analysis such as higher transport cost, lower demand, or changed reserve.

Authentication example

POST /api/v1/token
Content-Type: application/json

{
  "clientId": "auction-platform-service",
  "clientSecret": "<stored in vault or secret manager>"
}

Response fields to cache:
- accessToken
- tokenType = Bearer
- expiresUtc
- scopes such as decisioq.write or decisioq.admin

5. Data mapping rules

The quality of DecisioQ recommendations depends on consistent score definitions. Do not send raw fields unless all options use the same scale and meaning. Define field mappings in code or configuration, then test them with historical auction outcomes.

Auction source field	DecisioQ score	Scale recommendation	Notes
Projected gross minus acquisition and recon cost	ExpectedProfit	Currency value, higher is better	Use the same currency and time horizon across all lots.
Search activity, watch count, proxy bids, MMR/market demand signals	MarketDemand	0-100 or index, higher is better	Document how demand is calculated so weights remain meaningful.
CR score, inspection grade, mechanical/exterior/interior ratings	VehicleCondition	0-100, higher is better	Keep condition scale consistent across locations and inspectors.
Likely winning bid or current bid ceiling	PurchasePrice or BidAmount	Currency value, lower is better	Include buyer fees if your business treats them as acquisition cost.
Carrier quote or distance-based estimate	TransportationCost	Currency value, lower is better	Update before final decision if transport quote expires.
Expected turn time from acquisition to retail/wholesale sale	DaysToSell	Days, lower is better	Use modelled or historical segment averages.
Buyer payment score or floorplan reliability	PaymentReliability	0-100, higher is better	Keep compliance decisions separate from advisory scores when required.
Post-sale arbitration or complaint rate	DisputeRate	Percentage, lower is better	Use lookback windows that match business policy.

6. Implementation recipes

Recipe A: Vehicle Acquisition in a buyer workbench

1. Load candidate vehicles from upstream auctions, seller feeds, or internal sale inventory.
2. Calculate ExpectedProfit, MarketDemand, VehicleCondition, PurchasePrice, TransportationCost, and DaysToSell for each VIN or lot.
3. Send the Vehicle Acquisition template to /api/v1/decide with all candidates.
4. Display ranked vehicles, excluded vehicles, confidence, and explanation.
5. Store accepted recommendation with buyer, timestamp, source sale, and final bid/purchase outcome.

Recipe B: Bid Optimization during live or timed auction

1. Call DecisioQ before the auction lane starts, not for every bid increment unless latency and rate limits are proven.
2. Use Bid Optimization to rank candidate lots or recommend which vehicles deserve available budget.
3. Refresh scores when market demand, risk score, or bid amount changes materially.
4. Guardrail the output with maximum bid policies and buyer authority limits.
5. Use scenario analysis to compare current bid, +5 percent bid, and transport-cost shock cases.

Recipe C: Reserve Price Setting for consignor/seller tools

1. For each proposed reserve level, create one option with ExpectedSalePrice, SaleProbability, DaysInInventory, and MarketCompetition.
2. Run DecisioQ to rank reserve strategies; do not treat recommendation as a legal appraisal or guaranteed sale price.
3. Show explanation to seller managers: the API may prefer a slightly lower reserve when sale probability and days in inventory dominate.
4. Capture final human-approved reserve and reason for override if different from recommendation.

Recipe D: Transportation Vendor Selection after sale

1. Create one option per carrier quote.
2. Map price to TransportationCost, ETA to DeliveryTime, historical claims to DamageRate, available trucks to Capacity, and SLA performance to Reliability.
3. Apply the built-in Reliability >= 90 constraint or override with stricter enterprise policy.
4. Display the winning carrier and excluded carriers with exclusion reason.

7. Payload examples

Vehicle Acquisition request

{
  "template": "Vehicle Acquisition",
  "algorithm": "TOPSIS",
  "runSensitivity": true,
  "validationMode": "Strict",
  "options": [
    {
      "optionId": "VIN-1HGCM82633A004352",
      "name": "2019 SUV Lot 1842",
      "scores": {
        "ExpectedProfit": 4200,
        "MarketDemand": 82,
        "VehicleCondition": 76,
        "PurchasePrice": 14800,
        "TransportationCost": 625,
        "DaysToSell": 24
      }
    },
    {
      "optionId": "VIN-2FTRX18W1XCA01234",
      "name": "2020 Pickup Lot 2210",
      "scores": {
        "ExpectedProfit": 5100,
        "MarketDemand": 77,
        "VehicleCondition": 81,
        "PurchasePrice": 19300,
        "TransportationCost": 840,
        "DaysToSell": 31
      }
    },
    {
      "optionId": "VIN-JM1BL1V72C1509876",
      "name": "2018 Sedan Lot 775",
      "scores": {
        "ExpectedProfit": 2300,
        "MarketDemand": 69,
        "VehicleCondition": 73,
        "PurchasePrice": 9200,
        "TransportationCost": 410,
        "DaysToSell": 21
      }
    }
  ],
  "context": {
    "correlationId": "optional",
    "attributes": {}
  }
}

C# backend call pattern

public async Task<DecisionResponse?> DecideVehicleAcquisitionAsync(
    IReadOnlyList<AuctionVehicleCandidate> candidates,
    string accessToken,
    CancellationToken ct)
{
    var request = new
    {
        template = "Vehicle Acquisition",
        algorithm = "TOPSIS",
        runSensitivity = true,
        validationMode = "Strict",
        options = candidates.Select(v => new
        {
            optionId = v.Vin,
            name = $"{v.Year} {v.Make} {v.Model} Lot {v.LotNumber}",
            scores = new Dictionary<string, double>
            {
                ["ExpectedProfit"] = v.ExpectedProfit,
                ["MarketDemand"] = v.MarketDemandIndex,
                ["VehicleCondition"] = v.ConditionScore,
                ["PurchasePrice"] = v.EstimatedWinningBid,
                ["TransportationCost"] = v.TransportEstimate,
                ["DaysToSell"] = v.ExpectedDaysToSell
            }
        })
    };

    using var http = new HttpClient { BaseAddress = new Uri(_decisioQBaseUrl) };
    http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

    using var response = await http.PostAsJsonAsync("/api/v1/decide", request, ct);
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadFromJsonAsync<DecisionResponse>(cancellationToken: ct);
}

JavaScript/TypeScript backend call pattern

async function decideBidOptimization(candidates, token) {
  const body = {
    template: "Bid Optimization",
    algorithm: "TOPSIS",
    runSensitivity: true,
    options: candidates.map(lot => ({
      optionId: lot.lotId,
      name: `${lot.year} ${lot.make} ${lot.model}`,
      scores: {
        ExpectedROI: lot.expectedRoiPercent,
        BidAmount: lot.currentOrTargetBid,
        MarketDemand: lot.marketDemandIndex,
        RiskScore: lot.riskScore,
        VehicleCondition: lot.conditionScore
      }
    }))
  };

  const res = await fetch(`${process.env.DECISIOQ_URL}/api/v1/decide`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(body)
  });

  if (!res.ok) throw new Error(`DecisioQ failed: ${res.status} ${await res.text()}`);
  return await res.json();
}

8. UI and workflow integration

UI element	Recommended display	Why it matters
Top recommendation card	Winning option name, score/rank, confidence, and short explanation.	Users need a fast answer and a reason they can defend.
Ranked alternatives table	All passed options with rank, score, and key factor impacts.	Auction users often compare the winner against familiar alternatives.
Excluded options panel	Options removed by constraints and the failed threshold.	Prevents confusion when a known vehicle, seller, or carrier does not appear in the ranking.
What-if controls	Editable weights or scenario changes such as transport cost or market demand.	Supports human review before final bid, reserve, or lane action.
Accept/override action	Require user, timestamp, selected action, and override reason.	Creates an audit trail and training data for future calibration.

9. Production readiness checklist

• Store DecisioQ base URL, clientId, clientSecret, and JWT signing dependencies in a secret manager or vault.
• Use server-side token caching and refresh before expiresUtc.
• Validate every outbound DecisionRequest before calling DecisioQ; reject missing OptionId values and missing criterion scores.
• Protect /decide calls with idempotency or deduplication when users can click repeatedly.
• Persist raw request/response for audit, but tokenize or redact sensitive buyer/seller data if required by policy.
• Create monitoring for latency, HTTP errors, empty passed-options results, and unusual exclusion rates.
• Add fallback behavior: if DecisioQ is unavailable, keep the operational workflow usable and mark the decision as manual.
• Review weights with business owners monthly or whenever market conditions materially change.
• Use sensitivity results for high-dollar decisions; low confidence should trigger human approval rather than automation.
• Separate advisory recommendations from regulated compliance decisions unless legal and compliance teams approve the workflow.

10. Appendix: Auto Auction template catalog

Template	Built-in criteria
Vehicle Acquisition	Expected profit, demand, condition, purchase price, transport cost, days to sell.
Bid Optimization	Expected ROI, bid amount, demand, risk, condition.
Lane Scheduling	Revenue, buyer interest, volume, operational complexity.
Reserve Price Setting	Expected sale price, sale probability, inventory age, competition.
Seller Selection	Vehicle quality, sell-through, profit, dispute rate, volume.
Buyer Qualification	Purchase history, payment reliability, credit score, dispute history.
Vehicle Grading	Mechanical, exterior, interior, accident history, mileage, title status.
Inventory Liquidation	Inventory age, holding cost, sale price, demand, transport cost.
Transportation Vendor Selection	Transportation cost, delivery time, damage rate, capacity, reliability.

Appendix B: Common validation and troubleshooting

Symptom	Likely cause	Fix
400: Every option must contain an OptionId.	An option was sent without a stable identifier.	Use VIN, lot ID, buyer ID, seller ID, carrier ID, or generated internal UUID.
400: No options passed constraints.	All candidates failed template constraints such as ExpectedProfit >= 2500.	Show exclusions, ask user to loosen criteria, add more candidates, or change workflow.
Unexpected winner.	Criterion scale or direction is wrong.	Confirm that minimize factors are sent as raw values and criteria directions match business meaning.
Low confidence.	Top-ranked options are close or sensitive to weight changes.	Require human review or run scenario analysis.
Template not found.	Template name does not match catalog.	Call /api/v1/templates and use exact template names such as Vehicle Acquisition.

Appendix C: Deployment notes for Auto Auction platforms

For monolithic auction platforms, create an internal DecisioQ adapter module that centralizes token retrieval, request building, response parsing, logging, and error handling. For microservices, expose a dedicated decision-orchestration service so bidding, inventory, seller, buyer, and logistics modules do not duplicate mapping logic.

Do not hide DecisioQ explanations. In auction operations, a recommendation is most valuable when it is explainable: why a vehicle should be acquired, why a reserve is recommended, why a buyer is qualified, or why a carrier is selected. Persisting explanations also helps post-sale analysis and model calibration.