{"openapi":"3.1.0","info":{"title":"Carified Stock API","version":"v1","description":"Push a dealership’s stock from a DMS into its Carified Yard. Cars land in Getting Ready and never go on sale on their own: the dealer adds disclosures and publishes. A field is never cleared by leaving it out, and an odometer is never lowered.","contact":{"name":"Carified Support","url":"https://carified.com.au/account/support"}},"externalDocs":{"description":"Stock API docs","url":"https://carified.com.au/developers/stock-api"},"servers":[{"url":"https://carified.com.au/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/stock":{"get":{"operationId":"listStock","summary":"List the cars your API feed holds","responses":{"200":{"description":"The cars this dealership’s API feed holds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockList"},"example":{"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}]}}}},"401":{"description":"The key is missing, isn’t valid, or was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s dealership isn’t verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The dealership has a feed URL connected, or a full update is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Slow down: wait the Retry-After header’s seconds, then try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}}},"500":{"description":"Something went wrong on Carified’s side. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"replaceStock","summary":"Send a full update: the whole yard","description":"Up to 2000 cars and 10 MB. A car the feed holds that’s missing from 2 full updates in a row leaves, as if deleted. A car that can’t be read is a problem, not a failure.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"},"example":{"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"}]}}}},"responses":{"200":{"description":"What the full update changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResult"},"example":{"carsRead":2,"added":1,"updated":0,"unchanged":1,"left":0,"problems":[]}}}},"400":{"description":"The body isn’t JSON, the VIN isn’t one, a field isn’t one Carified knows, or a full update has more than 2,000 cars.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, isn’t valid, or was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s dealership isn’t verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The dealership has a feed URL connected, or a full update is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is too big: over 10 MB for a full update, or 256 KB for one car.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Slow down: wait the Retry-After header’s seconds, then try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}}},"500":{"description":"Something went wrong on Carified’s side. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stock/{vin}":{"parameters":[{"name":"vin","in":"path","required":true,"description":"The car’s VIN.","schema":{"type":"string","minLength":10,"maxLength":17},"example":"JTMBFREV10D123456"}],"put":{"operationId":"upsertCar","summary":"Add or update one car","description":"Idempotent: sending the same car twice changes nothing the second time.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vehicle"},"example":{"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"]}}}},"responses":{"200":{"description":"What happened to the car.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarResult"},"example":{"vin":"JTMBFREV10D123456","result":"added","problems":[]}}}},"400":{"description":"The body isn’t JSON, the VIN isn’t one, a field isn’t one Carified knows, or a full update has more than 2,000 cars.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, isn’t valid, or was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s dealership isn’t verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The dealership has a feed URL connected, or a full update is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is too big: over 10 MB for a full update, or 256 KB for one car.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Slow down: wait the Retry-After header’s seconds, then try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}}},"500":{"description":"Something went wrong on Carified’s side. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeCar","summary":"The car left your stock","description":"A car on sale comes off sale (it’s never marked sold: the dealer confirms a sale in Carified). A car getting ready is flagged “Not in your feed”.","responses":{"200":{"description":"What happened to the car.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveResult"},"example":{"vin":"JTMBFREV10D123456","result":"left"}}}},"401":{"description":"The key is missing, isn’t valid, or was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key’s dealership isn’t verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The dealership has a feed URL connected, or a full update is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Slow down: wait the Retry-After header’s seconds, then try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before trying again.","schema":{"type":"integer"}}}},"500":{"description":"Something went wrong on Carified’s side. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"A dealership API key (cfd_sk_ followed by 40 letters and digits), created by the dealership’s owner in Settings → Stock Feed."}},"schemas":{"Vehicle":{"type":"object","additionalProperties":false,"description":"One car. Only vin is required, and on PUT /stock/{vin} the path gives it.","properties":{"vin":{"type":"string","minLength":10,"maxLength":17,"description":"The car’s VIN (10–17 characters). On PUT /stock/{vin} the path gives it; if the body sends one too, they must match."},"externalId":{"type":["string","number"],"description":"Your system’s own id for the car."},"stockNumber":{"type":["string","number"],"description":"The yard’s stock number, shown to the dealer in Carified."},"year":{"type":["string","number"],"description":"Build year, e.g. 2021."},"make":{"type":["string","number"],"description":"e.g. “Toyota”. Matched to Carified’s make list."},"model":{"type":["string","number"],"description":"e.g. “RAV4”. Matched to Carified’s model list."},"variant":{"type":["string","number"],"description":"Badge or trim, e.g. “GXL Hybrid”."},"odometerKm":{"type":["string","number"],"description":"Kilometres. “45,210 km” is read, and miles (“28091 mi”) convert."},"price":{"type":["string","number"],"description":"Asking price in dollars, e.g. 38990 or “$38,990”. Under $500 reads as “call us”, so the car has no price."},"priceType":{"type":"string","description":"“drive_away” or “excl_govt_charges”. Google’s vehicle_price_type values and plain text like “Drive away” are read too.","examples":["drive_away","excl_govt_charges"]},"description":{"type":"string","maxLength":20000,"description":"The car’s write-up, as plain text."},"bodyType":{"type":["string","number"],"description":"e.g. “SUV”, “Ute”, “Sedan”."},"transmission":{"type":["string","number"],"description":"e.g. “Automatic” or “6 sp auto”."},"fuelType":{"type":["string","number"],"description":"e.g. “Petrol”, “Diesel”, “Hybrid”."},"driveType":{"type":["string","number"],"description":"e.g. “AWD”, “4x4”, “FWD”."},"colour":{"type":["string","number"],"description":"e.g. “Glacier White”."},"batteryKwh":{"type":["string","number"],"description":"Electric & plug-in hybrid: usable battery, e.g. 77.4 or “77.4 kWh”."},"rangeKm":{"type":["string","number"],"description":"Electric & plug-in hybrid: the maker’s range (a plug-in hybrid’s electric range), e.g. 507 or “507 km”."},"dcChargeKw":{"type":["string","number"],"description":"Electric & plug-in hybrid: peak DC fast charging, e.g. 235 or “235 kW”. Leave it out when there’s none."},"chargePort":{"type":["string","number"],"description":"Electric & plug-in hybrid: e.g. “CCS2”, “Type 2”, “CHAdeMO”."},"photoUrls":{"type":"array","maxItems":100,"items":{"type":"string","format":"uri"},"description":"Up to 100 http(s) URLs; the first is the hero. Fetched in the background, and a URL is never fetched twice."}}},"Snapshot":{"type":"object","additionalProperties":false,"required":["vehicles"],"properties":{"vehicles":{"type":"array","maxItems":2000,"items":{"$ref":"#/components/schemas/Vehicle"}}}},"CarResult":{"type":"object","required":["vin","result","problems"],"properties":{"vin":{"type":"string"},"result":{"type":"string","enum":["added","updated","unchanged","skipped"]},"problems":{"type":"array","items":{"type":"string"}}}},"RemoveResult":{"type":"object","required":["vin","result"],"properties":{"vin":{"type":"string"},"result":{"type":"string","enum":["left","not_in_feed"]}}},"SnapshotResult":{"type":"object","required":["carsRead","added","updated","unchanged","left","problems"],"properties":{"carsRead":{"type":"integer"},"added":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"left":{"type":"integer"},"problems":{"type":"array","items":{"type":"object","required":["line","vin","message"],"properties":{"line":{"type":"integer","description":"The car’s place in vehicles, from 1."},"vin":{"type":["string","null"]},"message":{"type":"string"}}}}}},"StockList":{"type":"object","required":["vehicles"],"properties":{"vehicles":{"type":"array","items":{"type":"object","required":["vin","externalId","stockNumber","status","syncing"],"properties":{"vin":{"type":"string"},"externalId":{"type":["string","null"]},"stockNumber":{"type":["string","null"]},"status":{"type":"string","enum":["getting_ready","for_sale","off_sale","sold"]},"syncing":{"type":"boolean","description":"False once the dealer chose Stop Syncing for the car, or once it left your feed."}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong, in plain English."}},"example":{"error":"Your API key isn’t valid. Create a new one in Settings → Stock Feed."}}}}}