SmartScore for developers

Quick start

1. Create a partner account on /partners/onboard.
2. Receive your publishable API key and trial access.
3. Run an instant vehicle test from the partner dashboard.
4. Integrate POST /api/sdk/smartscore in your stack.
5. Usage is billed monthly after trial limits are reached.

Start here: choose your API mode

All integrations call /api/sdk/smartscore. Select mode by commercial use case:

• listing for buyer-facing listing badges and reliability labels
• explain for plain-English support and operations output
• auction for pre-bid risk workflows and salvage screening
• warranty for underwriting and maintenance-risk decisions
• fraud for deterministic listing integrity and trust & safety scoring
• ultra for deepest enterprise intelligence

Ultra accepts useCase or marketVertical with values marketplace, auction, or warranty to tune sensitivity for your vertical.

Current calibration intent: warranty runs roughly 12–18% stricter than auction on repair-likelihood and exposure outputs, while marketplace stays buyer-friendly.

Mode coverage matrix

1. Add the SmartScore SDK

Drop a single script tag on your marketplace or OEM site. SmartScore scans your listing cards and injects a buyer-friendly badge.

<script
  src="https://YOURDOMAIN.com/smartscore-sdk.js"
  data-publishable-key="pk_live_partner123">
</script>

2. Mark up your listing cards

Add data attributes to each card. The SDK calls your endpoint at /api/sdk/smartscore and renders the badge.

<div class="vehicle-card"
     data-smartscore-asset="AB12CDE"
     data-smartscore-type="car">
  <span class="price">£7,495</span>
  <span class="smartscore-badge-mount"></span>
</div>

For properties, yachts or jets, set data-smartscore-type="home" | "commercial" | "yacht" | "jet".

3. API flow used by the SDK

The public SDK calls /api/sdk/smartscore, which then routes to internal engines:

• /api/score for SmartScore reliability scoring
• /api/predict for expected yearly maintenance and 12-month repair likelihood
• /api/dvsa/mot for UK inspection history (vehicles only)
• /api/sdk/fraud for standalone fraud and listing integrity signals

Ultra mode adds richer decision signals and buyer-friendly explanations for enterprise partners.

4. Listing mode request + response

Buyer-facing listing intelligence for marketplace cards and dealer stock pages.

POST /api/sdk/smartscore
{
  "assetType": "car",
  "assetId": "AB12CDE",
  "publishableKey": "pk_live_partner123",
  "mode": "listing"
}

{
  "score": 84,
  "category": "Good",
  "reliabilityBand": "Good",
  "riskPercent": 12,
  "repairExposureLow": 220,
  "repairExposureHigh": 520,
  "listingFraudScore": 18,
  "listingFraudLevel": "Low"
}

5. Explain mode request + response

Plain-English intelligence for support teams and buyer decision context.

POST /api/sdk/smartscore
{
  "assetType": "car",
  "assetId": "AB12CDE",
  "publishableKey": "pk_live_partner123",
  "mode": "explain"
}

{
  "score": 71,
  "category": "Fair",
  "riskPercent": 19,
  "buyerRepairEstimateLow": 380,
  "buyerRepairEstimateHigh": 790,
  "hiddenLossSignal": { "level": "Moderate" },
  "narrative": { "overallImpression": "..." }
}

6. Auction mode request + response

Pre-bid intelligence for auction lanes and salvage triage.

POST /api/sdk/smartscore
{
  "assetType": "car",
  "assetId": "AB12CDE",
  "publishableKey": "pk_live_partner123",
  "mode": "auction"
}

{
  "score": 58,
  "category": "Review recommended",
  "riskPercent": 29,
  "suggestedBidAdjustmentPercent": -12,
  "auctionRiskBand": "Elevated",
  "listingFraudLevel": "Medium"
}

7. Warranty mode request + response

Underwriting-focused output for reserve and claims-risk control.

POST /api/sdk/smartscore
{
  "assetType": "car",
  "assetId": "AB12CDE",
  "publishableKey": "pk_live_partner123",
  "mode": "warranty"
}

{
  "score": 63,
  "category": "Fair",
  "riskPercent": 24,
  "underwritingExposureLow": 610,
  "underwritingExposureHigh": 1280,
  "failureProbability12m": 0.24
}

8. Fraud intelligence request example

Use fraud mode when you need explicit listing anomaly checks for trust and safety workflows.

POST /api/sdk/smartscore
{
  "assetType": "car",
  "assetId": "AB12CDE",
  "publishableKey": "pk_live_partner123",
  "mode": "fraud",
  "price": 7995,
  "expected_price_band": { "low": 9200, "high": 10800 },
  "text": "bank transfer only, no viewing"
}

9. Ultra mode request example

Use Ultra for highest-sensitivity decisions. Set either useCase or marketVertical to apply the right calibration profile.

POST /api/sdk/smartscore
{
  "assetType": "car",
  "assetId": "AB12CDE",
  "publishableKey": "pk_live_partner123",
  "mode": "ultra",
  "useCase": "warranty"
}

Accepted profiles: marketplace, auction, warranty.