Modulynk Dealership OS — Developer API Documentation

🔑 Authentication

All requests to the Modulynk REST API require an authorized API key passed via the X-API-Key request header.

Header Specification

X-API-Key: mk_live_xxxxxxxxxxxxxxxxxxxxxxxx

How to generate your API Key:

Open your Dealership OS Settings Panel.
Locate the 🔑 API Access & Keys section.
Enter a label (e.g. Website Trade-In Lead Widget) and click ＋ Generate Key.
Copy your live key (format: mk_...). It is instantly cryptographically linked to your merchant tenant.

⚡ Quickstart (cURL)

Fetch your active dealership pipeline with a single command:

cURL Example

curl -X GET "https://modulynk-app.web.app/api/v1/tradein/quotes" \
  -H "X-API-Key: YOUR_API_KEY"

GET List Trade-In Quotes

Returns a list of quotes and vehicle leads matching your dealership account. Supports filtering by pipeline stage.

GET /api/v1/tradein/quotes

Query Parameters

Parameter	Type	Description
`stage`	string (optional)	Filter by pipeline stage (`new_submission`, `under_review`, `offer_sent`, `accepted`, `inspection_booked`, `inspected`, `contract_payment`).
`limit`	number (optional)	Maximum records to return (default: `50`).

Response Example (200 OK)

{
  "success": true,
  "count": 1,
  "quotes": [
    {
      "id": "Q-X91KA2",
      "stage": "offer_sent",
      "status": "offer_sent",
      "rego": "CY82LP",
      "state": "NSW",
      "customer": {
        "name": "Sarah Jenkins",
        "phone": "+61412345678",
        "email": "sarah.j@example.com.au"
      },
      "vehicle": {
        "vin": "6T1AA110000000001",
        "year": 2020,
        "make": "Toyota",
        "model": "RAV4",
        "odometer": 42000
      },
      "offeredAmount": 31500,
      "benchmarkMid": 32000,
      "offerUrl": "https://modulynk-app.web.app/dealership-offer.html?id=Q-X91KA2&dealer=dealer_123",
      "createdAt": "2026-10-15T02:15:00.000Z"
    }
  ]
}

GET Get Single Quote by ID

Retrieve complete condition declarations, valuation history, and vehicle metadata for a single lead.

GET /api/v1/tradein/quotes/:id

Response Example (200 OK)

{
  "success": true,
  "quote": {
    "id": "Q-X91KA2",
    "stage": "offer_sent",
    "rego": "CY82LP",
    "state": "NSW",
    "customer": {
      "name": "Sarah Jenkins",
      "phone": "+61412345678"
    },
    "vehicle": {
      "year": 2020,
      "make": "Toyota",
      "model": "RAV4",
      "odometer": 42000
    },
    "offeredAmount": 31500,
    "offerUrl": "https://modulynk-app.web.app/dealership-offer.html?id=Q-X91KA2&dealer=dealer_123"
  }
}

POST Create Trade-In Lead / Quote

Submit an inbound trade-in lead directly into your pipeline from an external website form, dealer aggregator, or landing page.

⚡ Automated Rego-to-Specs Resolution: You do not need to make a separate registry lookup. Passing simply rego and state automatically queries Modulynk's multi-tier Australian registry gateway, resolves make, model, year, body type, transmission, fuel, and VIN, estimates vehicle mileage, and computes valuation benchmarks immediately.

POST /api/v1/tradein/quotes

JSON Body Parameters

Field	Type	Description
`rego` / `plate`	string (required*)	Australian registration plate (e.g. `DK29QA`). Required unless `vin` is provided.
`state`	string (required)	State of registration (`NSW`, `VIC`, `QLD`, `WA`, `SA`, `TAS`, `ACT`, `NT`). Strictly required.
`photos`	array (optional)	Array of vehicle photos. Supports Base64 data URLs (`data:image/jpeg;base64,...`), raw Base64 strings, or image URLs. Uploaded to cloud storage and rendered in your dealership appraisal worksheet.
`customer.name` / `name`	string (optional)	Full name of vehicle seller (defaults to "Private Seller").
`customer.phone` / `phone`	string (optional)	Mobile phone number for automated 24-hour review acknowledgment SMS.
`customer.email` / `email`	string (optional)	Customer contact email address.
`vehicle.make` / `make`	string (optional)	Vehicle make (e.g. `Toyota`). If omitted, automatically resolved from the Australian registry.
`vehicle.model` / `model`	string (optional)	Vehicle model (e.g. `RAV4`). If omitted, automatically resolved from the Australian registry.
`vehicle.year` / `year`	number (optional)	Model year (e.g. `2021`). Auto-resolved if omitted.
`vehicle.odometer` / `odometer`	number (optional)	Odometer in km. If omitted, estimated based on vehicle age (~13,500 km/year).
`priceExpectation`	number (optional)	Seller's target dollar expectation. Automatically calculates price gap and priority flag.

Payload Example 1: Minimal Rego-Only (Auto-Resolves Specs & Valuation)

{
  "rego": "DK29QA",
  "state": "NSW",
  "name": "Alex Miller",
  "phone": "0412345678"
}

Payload Example 2: Intake with Photos & Declarations

{
  "rego": "DK29QA",
  "state": "NSW",
  "name": "Sarah Connor",
  "phone": "0412345678",
  "email": "sarah.c@example.com",
  "photos": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "https://images.example.com/cars/interior.jpg"
  ],
  "priceExpectation": 18500,
  "notes": "One owner, always garaged, full service logbook"
}

Response Example (201 Created)

{
  "success": true,
  "id": "TI-K9M4Z2",
  "stage": "new_submission",
  "priority": "High",
  "vehicle": "2021 Toyota RAV4",
  "rego": "DK29QA",
  "state": "NSW",
  "vin": "JTMDFREV20D...",
  "odometer": 54000,
  "photoCount": 2,
  "photos": [
    {
      "url": "https://firebasestorage.googleapis.com/.../photo_1.jpg",
      "slot": "exterior",
      "title": "Photo 1"
    }
  ],
  "benchmark": {
    "low": 24000,
    "mid": 26500,
    "high": 28500,
    "retail": 31000
  },
  "slaExpiresAt": "2026-10-16T22:15:00.000Z",
  "offerUrl": "https://modulynk-app.web.app/dealership-offer.html?id=TI-K9M4Z2&dealer=dealer_123",
  "message": "Trade-in quote created in dealership pipeline."
}

POST Upload Photos to Existing Quote

Append additional vehicle photos to an existing quote in your pipeline.

POST /api/v1/tradein/quotes/:id/photos

Payload Example

{
  "photos": [
    "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    {
      "dataUrl": "data:image/jpeg;base64,/9j/4AAQSk...",
      "slot": "odometer",
      "title": "Cluster Mileage"
    }
  ]
}

Response Example (200 OK)

{
  "success": true,
  "id": "TI-K9M4Z2",
  "addedCount": 2,
  "totalPhotos": 4,
  "photos": [ ... ]
}

POST Update Quote Pipeline Stage

Allows an external Dealer Management System (DMS) or CRM to synchronize stage progression (e.g. marking a deal as accepted or inspected).

POST /api/v1/tradein/quotes/:id/stage

Payload Example

{
  "stage": "accepted",
  "notes": "Seller confirmed conditional cash offer via phone consultation"
}

📋 Error Codes

HTTP Status	Error Code / Message	Remedy
`400 Bad Request`	`MISSING_REQUIRED_FIELD / INVALID_STATE`	Missing required parameter (e.g. `state`, `rego`, or `customer.name`). State must be one of: NSW, VIC, QLD, WA, SA, TAS, ACT, NT.
`401 Unauthorized`	`X-API-Key header required / Invalid API Key`	Check that your API key is generated in your Dealership Settings and passed in the `X-API-Key` header.
`404 Not Found`	`Quote #... not found`	Verify the quote ID exists in your authenticated dealership account.
`429 Too Many Requests`	`REGISTRY_RATE_LIMITED`	PlateAPI / vehicle registry lookup rate limit reached (1 lookup/minute). Enter the vehicle's 17-character VIN directly or retry after 60 seconds.
`500 Server Error`	`Internal server error`	An unexpected server error occurred. Retry request or contact Modulynk support.

PlateAPI Rate Limit Error Response (HTTP 429)

{
  "error": "Vehicle registry lookup rate limit reached. Please enter the 17-character VIN directly or retry in 60 seconds.",
  "code": "REGISTRY_RATE_LIMITED",
  "retryAfter": 60
}