Check for a match

Ask whether Studio Instant can serve a VIN before you commit to it. A check creates nothing, uses no credits and is safe to repeat.

POSThttps://api.spyne.ai/api/pv1/instant

AuthBearer tokenRate limit120 requests / min per rooftop keyCreditsNone

You can skip this step: a generate runs the same check itself.

Before you call it

Studio Instant must be on for the rooftop and the vehicle's condition (new or used), or the call answers 403 INSTANT_NOT_ENABLED.
Send the vehicle details Spyne doesn't already have; see Which vehicle details to send.

Counts toward the 120 requests a minute per rooftop key, shared with generates.

Request body

Requiredalways sendRequired ifrequired only in the case describedOptionalcan be left out

Request checklist

Name the vehicle: send vin.
Only check: send checkOnly: true.
Fill the gaps: send any of the seven details Spyne doesn't know. For a new VIN, send at least exteriorColor, interiorColor and condition.
Group key: add rooftopId.

Parameter	Type	Required	Description
`vin`	string	Required	The 17-character VIN of the vehicle that needs images. Letters and digits only, never I, O or Q. Lower case is accepted and upper-cased for you.
`checkOnly`	boolean	Required	Send `true`: only check for a match. Nothing is created and no credits are used.
Vehicle details	—	Required if	Required when Spyne doesn't know the vehicle. A match needs all seven; see Which details to send.
`year`	number, or a 4-digit string	Required if	Model year, from 1981 to two years ahead. Filled from the VIN when it can be decoded.
`make`	string	Required if	For example `Toyota`. Filled from the VIN when it can be decoded.
`model`	string	Required if	For example `Camry`. Filled from the VIN when it can be decoded.
`trim`	string	Required if	For example `XLE`. Filled from the VIN when the decode has it.
`exteriorColor`	string	Required if	The body colour as the dealer names it, for example `Midnight Black Metallic`.
`interiorColor`	string	Required if	The interior colour, for example `Black`.
`condition`	string	Required if	`new` or `used`. Send `used` for certified pre-owned, demo and rental units too.
`stockNumber`	string	Optional	The dealer's stock number. Only used by a generate, which saves it on the vehicle.
`rooftopId`	string	Required if	Group-level keys only: which rooftop the vehicle belongs to. Leave it out with a rooftop key.

Text fields take at most 255 characters.

Sample request

curl --request POST \
  --url 'https://api.spyne.ai/api/pv1/instant' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "vin": "4T1BZ1HK5KU012345",
    "checkOnly": true,
    "year": 2024,
    "make": "Toyota",
    "model": "Camry",
    "trim": "XLE",
    "exteriorColor": "Midnight Black Metallic",
    "interiorColor": "Black",
    "condition": "used"
  }'

import requests

url = "https://api.spyne.ai/api/pv1/instant"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "vin": "4T1BZ1HK5KU012345",
    "checkOnly": True,
    "year": 2024,
    "make": "Toyota",
    "model": "Camry",
    "trim": "XLE",
    "exteriorColor": "Midnight Black Metallic",
    "interiorColor": "Black",
    "condition": "used",
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code, response.json())

const response = await fetch("https://api.spyne.ai/api/pv1/instant", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    vin: "4T1BZ1HK5KU012345",
    checkOnly: true,
    year: 2024,
    make: "Toyota",
    model: "Camry",
    trim: "XLE",
    exteriorColor: "Midnight Black Metallic",
    interiorColor: "Black",
    condition: "used",
  }),
});
console.log(response.status, await response.json());

Sample response

{
  "success": true,
  "statusCode": 200,
  "message": "A Studio Instant match exists for this VIN",
  "data": {
    "vin": "4T1BZ1HK5KU012345",
    "matched": true,
    "vehicle": {
      "year": 2024,
      "make": "Toyota",
      "model": "Camry",
      "trim": "XLE",
      "exteriorColor": "Midnight Black Metallic",
      "interiorColor": "Black",
      "condition": "used"
    }
  }
}

Result	`data.matched`	`message`	What to do
A match exists	`true`	"A Studio Instant match exists for this VIN"	Generate the Instant set.
No match	`false`	"No Studio Instant match exists for this VIN right now"	Plan a photo shoot for this vehicle instead.
Already Instant	`true`	"This VIN already has a Studio Instant image set"	Go straight to Read status and images.

All three answer 200 in the same shape.

Response parameters (200)

Parameter	Type	Description
`data.vin`	string	The VIN you sent, upper-cased.
`data.matched`	boolean	`true` if Studio Instant can build (or already built) a set for this VIN; `false` if not.
`data.vehicle`	object	Your vehicle's seven details as Spyne used them for the match, after filling gaps from inventory or the VIN. It never describes the vehicle the images come from.

A match means one exists now. Inventory changes, so a generate a few minutes later can still answer no_match.

Errors

Status	Code	When it happens
`400`	`INVALID_REQUEST`	A field is missing or invalid. Each problem is listed in `details.errors`.
`400`	`INVALID_REQUEST`	"stockNumber is already used by another vehicle at this rooftop".
`401`	`UNAUTHORIZED`	The key is missing, wrong or expired.
`403`	`INSTANT_NOT_ENABLED`	Studio Instant is off for this rooftop and vehicle condition (new or used).
`404`	`ROOFTOP_NOT_FOUND`	`rooftopId` isn't a rooftop this key can use.
`409`	`VEHICLE_HAS_PHOTOS`	The vehicle already has its own processed photos (or the dealer declined Instant for it).
`409`	`VEHICLE_IN_OTHER_ROOFTOP`	The VIN belongs to another rooftop's inventory.
`429`	`RATE_LIMITED`	More than 120 requests in a minute.
`503`	`SERVICE_UNAVAILABLE`	A Spyne service was briefly unavailable, or a generate for this VIN is already running.

A missing-details answer looks like this:

{
  "success": false,
  "statusCode": 400,
  "code": "INVALID_REQUEST",
  "message": "exteriorColor is required: this VIN isn't in the rooftop's inventory with an exterior color; condition is required: this VIN isn't in the rooftop's inventory with a condition (new or used)",
  "details": {
    "errors": [
      "exteriorColor is required: this VIN isn't in the rooftop's inventory with an exterior color",
      "condition is required: this VIN isn't in the rooftop's inventory with a condition (new or used)"
    ]
  }
}

Every code is explained in Errors and FAQs.

What happens next

On a match, generate the Instant set with the same body, without checkOnly.