Stock API

The Stock API is for DMS vendors and for dealerships with their own systems. It’s the push version of a stock feed: instead of us reading a feed file on a schedule, your system tells us the moment a car changes.

• Cars you send land in the dealership’s Yard as Getting Ready. They never go on sale on their own: the dealer adds the disclosures buyers see and publishes.
• For cars your feed holds, we keep the price, odometer, stock number, specs and photos in step with what you send.
• Every call is safe to repeat: sending the same car twice changes nothing.

Every path below starts with the base URL:

https://carified.com.au/api/v1

A key belongs to one dealership, and only that dealership’s owner can create one. The dealership must be verified on Carified first.

1. The owner signs in and opens Settings → Stock Feed in the dealer dashboard.
2. Under Push API, they create a key and name it after the system that will use it.
3. The key is shown once. Copy it into your system straight away: we keep only a hash, so we can’t show it again.

Keys can be revoked from the same place at any time, and a revoked key stops working immediately. If you build for many dealerships, ask each one for its own key.

Send the key as a bearer token on every request. Keys look like cfd_sk_ followed by 40 letters and digits. Keep them on your server, never in a browser or app.

Authorization: Bearer cfd_sk_YOUR_API_KEY_HERE

Requests and responses are JSON. An error always comes back as an error in plain English, with the HTTP status telling you what kind it is (see Errors).

{
  "error": "Your API key isn’t valid. Create a new one in Settings → Stock Feed."
}

4 endpoints cover it. Most systems send single cars as they change and a full update once a day, so anything missed along the way catches up.

curl -X PUT https://carified.com.au/api/v1/stock/JTMBFREV10D123456 \
  -H "Authorization: Bearer cfd_sk_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vin":"JTMBFREV10D123456","externalId":"DMS-48213","stockNumber":"S1042","year":2021,"make":"Toyota","model":"RAV4","variant":"GXL Hybrid","odometerKm":45210,"price":38990,"priceType":"drive_away","description":"One owner, full Toyota service history, 2 keys.","bodyType":"SUV","transmission":"CVT auto","fuelType":"Hybrid","driveType":"AWD","colour":"Glacier White","photoUrls":["https://cdn.example-dms.com.au/s1042/1.jpg","https://cdn.example-dms.com.au/s1042/2.jpg"]}'

{
  "vin": "JTMBFREV10D123456",
  "result": "added",
  "problems": []
}

curl -X DELETE https://carified.com.au/api/v1/stock/JTMBFREV10D123456 \
  -H "Authorization: Bearer cfd_sk_YOUR_API_KEY_HERE"

{
  "vin": "JTMBFREV10D123456",
  "result": "left"
}

curl -X PUT https://carified.com.au/api/v1/stock \
  -H "Authorization: Bearer cfd_sk_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vehicles":[{"vin":"JTMBFREV10D123456","externalId":"DMS-48213","stockNumber":"S1042","year":2021,"make":"Toyota","model":"RAV4","variant":"GXL Hybrid","odometerKm":45210,"price":38990,"priceType":"drive_away","description":"One owner, full Toyota service history, 2 keys.","bodyType":"SUV","transmission":"CVT auto","fuelType":"Hybrid","driveType":"AWD","colour":"Glacier White","photoUrls":["https://cdn.example-dms.com.au/s1042/1.jpg","https://cdn.example-dms.com.au/s1042/2.jpg"]},{"vin":"MR0HA3CD100654321","stockNumber":"S1057","year":2019,"make":"Toyota","model":"HiLux","price":"$41,500"}]}'

{
  "carsRead": 2,
  "added": 1,
  "updated": 0,
  "unchanged": 1,
  "left": 0,
  "problems": []
}

curl -X GET https://carified.com.au/api/v1/stock \
  -H "Authorization: Bearer cfd_sk_YOUR_API_KEY_HERE"

{
  "vehicles": [
    {
      "vin": "JTMBFREV10D123456",
      "externalId": "DMS-48213",
      "stockNumber": "S1042",
      "status": "for_sale",
      "syncing": true
    },
    {
      "vin": "MR0HA3CD100654321",
      "externalId": "DMS-48377",
      "stockNumber": "S1057",
      "status": "getting_ready",
      "syncing": true
    }
  ]
}

Only vin is required. Loose text is fine: we read values like “6 sp auto”, “45,210 km” or “$38,990” the same way we read a feed file. Fields we don’t know are refused, so a typo shows up straight away.

• Nothing goes on sale by itself. New cars wait in Getting Ready until the dealer adds disclosures and publishes them.
• Your system owns the details it sends. For cars your feed holds, price, odometer, stock number, specs and photos follow what you send, including on cars already on sale. A dealer who wants to edit a car by hand can Stop Syncing it.
• Leaving a field out never clears it. Send only what you know; what’s already there stays.
• An odometer is never lowered. A lower reading comes back as a problem for the dealer to look at.
• Photos sync in the background. The first URL is the hero. We fetch each URL once, so give a changed photo a new URL.
• One way in per dealership. While a feed URL is connected in Settings → Stock Feed, the API answers 409. Disconnect the feed to use the API instead.

Every error has an error message that says what to fix. Retry a 409, 429 or 500 later; fix the request for anything else.

• About 120 single-car calls a minute per key.
• 60 stock lists a minute per key.
• 256 KB per single car.
• 6 full updates per 10 minutes per key, one at a time.
• Full updates up to 2,000 cars and 10 MB.
• Up to 100 photo URLs per car, over http or https.

Over a limit, you’ll get a 429 with a Retry-After header in seconds. Wait that long, then carry on.

The OpenAPI file describes every endpoint and field, ready to load into Postman, Insomnia or a code generator.

Questions, or building for a DMS many dealers use? Sign in to your Carified account and contact us through the Support page, and we’ll help you get set up.