Cuvrd REST API

Single Vehicle Subscription VSC API - v1

Current Version

1.1.1, Updated August 14, 2023

Overview

The purpose of this API is to allow you to obtain Monthly Payment Subscription Extended Warranty/Vehicle Service Contract pricing for your customer's vehicles for display in your app or website, as well as provide a personalized link for that customer to your organization's whitelabel website so that they may purchase subscription extended warranty coverage.

The Cuvrd Single Vehicle Subscription VSC API is a single-step process: send us your customer's info and you'll get pricing and a link in return.

Our primary goal is to make it as simple as possible for you to get the universe of plans and pricing available for your customer's vehicle. We only ask for the vehicle's VIN (or Year, Make, and Model), current mileage, and the customer's state (along with your API credentials) to price out our plans.

In return, you will receive a summary pricing information as well as a personalized link for your customer to purchase a plan for their vehicle.

Personalized link info

If you pass your customer's personal information (such as name/address/email/phone), that data will be encrypted using a hash in the personalized link the API returns. This data is unlocked when your customer clicks on the personalized link, and is used to pre-fill their information during the checkout process.

If you do not wish to have your customer's data pre-filled during checkout, simply do not provide this data during the price request.

We do, however, encourage you to at the very least provide a unique customer_id for each record that ties to a value in your system.

Sample requests

We provide sample API calls next to each method using cURL. All you need to do is insert your specific parameters, and you can test the calls from the command line. See this tutorial on using cURL with APIs.

You can also use Postman if you aren't familiar with cURL. Postman is an easy-to-use API development and testing platform. If you prefer to work with our Postman collection, contact us for access to the latest version.

Requests and response

Both request body data and response data are formatted as JSON. Content type for responses will always be application/json.

Errors

The Cuvrd Term VSC API provides detailed, user-friendly error codes to aid with development and debugging.

More details regarding error responses are located in the errors section toward the bottom of this page.

The API will typically respond with a status of 200, even in cases involving authentication errors.

Occasionally, the API may respond with a 404 or a 50x error, and is an indication that we've probably screwed something up and are working to fix it.

Please contact us and let us know right away if you receive anything other than status 200.

Subscription API URL

The Cuvrd Subscription production API is located at:

https://api.cuvrd.com

The Cuvrd Subscription testing API is located at:

https://api.demo.cuvrd.com

Note: The Subscription API URLs are different than the Term VSC API URLs.

Authentication

Credentials are passed to the API in the URL of the request as query parameters. There is no need to pass authentication credentials as a header. Our API requires two query parameters: apiKey and whitelabel.

Your organization will be issued production Subscription API credentials after you sign up with Cuvrd.

You may use the testing credentials provided in the next section in our test environment.

Testing Query Parameters

Testing Vendor ID:

whitelabel=api-testing-website

Testing API Key:

apiKey=CV.KbHvHnUrPUs1UcPuep.OFwBG24zLxRudK61Sy

Note: Test credentials work only in the testing environment--they do not work in production.

Documentation

Subscription Price/Personalized Link Request

Subscription API Endpoint:

POST /api/vendor/personalized-offer

Subscription API Full URL Example:

POST https://api.demo.cuvrd.com/api/vendor/personalized-offer?apiKey=CV.KbHvHnUrPUs1UcPuep.OFwBG24zLxRudK61Sy&whitelabel=api-testing-website

Header:

Content-Type: application/json

Body Parameters

Key/Type Required Description
vin
string		 Yes* 17 character vehicle identification number.
*Required if year, make, and model are not sent.
If vin is provided, year, make, and model will be ignored.
year
string		 Yes* Vehicle year.
*Required if vin is not sent.
Will be ignored if vin is provided.
make
string		 Yes* Vehicle make.
*Required if vin is not sent.
Will be ignored if vin is provided.
model
string		 Yes* Vehicle model.
*Required if vin is not sent.
Will be ignored if vin is provided.
series
string		 No Extended vehicle model information.
mileage
integer		 No The vehicle's current mileage.
customer_id
string		 No Your internal unique ID for this Customer.
first_name
string		 No Customer's first name.
last_name
string		 No Customer's last name.
email
string		 No Customer's email address.
phone
string		 No Customer's 10 digit phone number, digits only.
address
string		 No Customer's street address.
address_2
string		 No Apt, Unit, etc.
city
string		 No Customer's city.
state_id
string		 No Customer's 2 letter state code, all caps.
zip
string		 No Customer's 5 digit zip code.

Notes:

– state_id and zip are not required but more accurate offers will be generated if one of the two are provided. If both state_id and zip are provided state_id takes prescedence over zip.

– mileage is not required but the API will return more accurate offers if provided. If mileage is not provided, mileage will be estimated at 1,000 miles per month of vehicle service, beginning in October of the year prior to the model year (i.e.: 2021 Ford Escape will have an estimated in-service date of October 1, 2020)

cURL example

curl --location --request POST 'https://api.demo.cuvrd.com/api/vendor/personalized-offer?apiKey=CV.KbHvHnUrPUs1UcPuep.OFwBG24zLxRudK61Sy&whitelabel=api-testing-website' \
--header 'Content-Type: application/json' \
--data-raw '{
  "vin": "JTMRFREV1JJ192877",
  "year": null,
  "make": null,
  "model": null,
  "series": null,
  "mileage": 36001,
  "customer_id":"ABC12345",
  "first_name": "Buddy",
  "last_name": "DuBuque",
  "email": "info@cuvrd.com",
  "phone": "8889991212",
  "address": "123 Any Street",
  "address_2": null,
  "city": "Norwichville",
  "state_id": "WV",
  "zip": "01234"
}'

Sample JSON

{
  "vin": "JTMRFREV1JJ192877",
  "year": null,
  "make": null,
  "model": null,
  "series": null,
  "mileage": 36001,
  "customer_id":"ABC12345",
  "first_name": "Buddy",
  "last_name": "DuBuque",
  "email": "info@cuvrd.com",
  "phone": "8889991212",
  "address": "123 Any Street",
  "address_2": null,
  "city": "Norwichville",
  "state_id": "WV",
  "zip": "01234"
}

Price Request Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Single Vehicle Subscription Vendor API - Price request",
  "description": "Subscription contract price request schema.",
  "anyOf": [
    { "required": [
        "vin"
      ]},
    { "required": [
        "year",
        "make",
        "model"
      ]},
    ],
    "vin": {
      "type": "string",
      "minLength": 17,
      "maxLength": 17,
      "description": "17 character alphanumeric VIN of the vehicle. If vin is provided, year, make, and model will be ignored.",
      "example": "3C63R3GL3JG236800"
    },
    "year": {
      "type": "string",
      "minLength": 4,
      "maxLength": 4,
      "description": "Vehicle year",
      "example": "2018"
    },
    "make": {
      "type": "string",
      "description": "Vehicle make",
      "example": "TOYOTA"
    },
    "model": {
      "type": "string",
      "description": "Vehicle model",
      "example": "CAMRY"
    },
    "series": {
      "type": "string",
      "description": "Extended vehicle model information",
      "example": "CAMRY XLE"
    },
    "mileage": {
      "type": "integer",
      "minimum": 1,
      "maximum": 999999,
      "description": "The vehicle's current mileage"
    },
    "customer_id": {
      "type": "string",
      "maxLength": 20,
      "description": "Your internal unique ID for this Customer"
      },
    "first_name": {
      "type": "string",
      "maxLength": 20,
      "description": "Customer's last name"
      },
    "last_name": {
      "type": "string",
      "maxLength": 20,
      "description": "Customer's last name"
      },
   "email": {
      "type": "string",
      "maxLength": 30,
      "description": "Customer's email address"
      },
    "phone": {
      "type": "string",
      "minLength": 10,
      "maxLength": 10,
      "description": "Customer's 10 digit phone number - digits only",
      "example": "3125551212"
      },
    "address": {
      "type": "string",
      "maxLength": 30,
      "description": "Customer's street address"
      },
    "address_2": {
      "type": "string",
      "maxLength": 30,
      "description": "Apt, Unit, etc."
      },
    "city": {
      "type": "string",
      "maxLength": 20,
      "description": "Customer's city"
      },
    "state_id": {
      "type": "string",
      "enum": ["AL","AK","AZ","AR","CA","CO","CT","DC","DE","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],
      "maxLength": 2,
      "description": "Customer's 2 letter state of residence code, all caps - required to offer coverage based on state restrictions."
      }
    "zip": {
      "type": "string",
      "minLength": 5,
      "maxLength": 5,
      "description": "Customer's 5 digit zip code",
      "example": "02184"
      }
  }

Subscription Price/Personalized Link Request Response

Response Parameters

Key/Type Required Description
error
string		 No A clear-text description of the error that has occurred.
request_uuid
string		 No Our UID for this request.
vendor_customer_id
string		 No Our UID for this request.
vin
string		 No The VIN for this vehicle. If no VIN was submitted, we will return a masked VIN with asterisks in positions 9 and 11-17.
promo
string		 No The promo code for this particular pricing offer. This code can be entered manually in our webisite in leiu of the customer's vehicle year, make, and model. Also passed in personalized_url.
mileage
integer		 No Current mileage on this vehicle.
state_id
string		 No Customer's 2 letter state of residence code, all caps.
personalized_url
string		 No Direct link to your whitelabel website that provides pricing for this customer/vehicle.
offers
array		 No Array comprised of available plans for this vehicle.
year
string		 No Vehicle year.
make
string		 No Vehicle make.
model
string		 No Vehicle model.
series
string		 No Extended vehicle model information.
no_plans_available
boolean		 No true = no coverage available for this vehicle.false = coverage is available for this vehicle.
vehicle_match
boolean		 No true = an exact match was found in our database for this vin or year/make/model.
false = we were not able to perfectly match this vehicle with an entry in our database-we are returning the best possible match
precise_mileage
boolean		 No true = mileage was passed in the request and pricing was based on that mileage.
false = mileage was not passed, current mileage was estimated based on vehicle age.
estimated_pricing
boolean		 No true = pricing for this vehicle is estimated due to precise_mileage = false or vehicle_match = false.
false = pricing for this vehicle is not estimated
lowest_price
number		 No Lowest monthly subscription price returned in the offers array.
lowest_price_plan_hash
string		 No 64 character alphanumeric id for the lowest price service contract/deductible combination returned in the offers array.
expires
integer		 No UNIX/Epoch time stamp representing the time this personalized link expires.
first_name
string		 No Customer's first name.
last_name
string		 No Customer's last name.
email
string		 No Customer's email address.
phone
string		 No Customer's 10 digit phone number, digits only.
address
string		 No Customer's street address.
address_2
string		 No Apt, Unit, etc.
city
string		 No Customer's city.
zip
string		 No Customer's 5 digit zip code.
covered_parts_url
string		 No URL to obtain the coverage details for the lowest price plan offered.

offers  Parameters

Key/Type Required Description
productRateIdHash
string		 Yes 64 character alphanumeric id for this specific service contract/deductible combination.
monthlySubscription
number		 Yes Subscription amount paid monthly starting no sooner than 30 days from the purchase date.
registrationFee
number		 Yes Amount due at the time of purchase.
plan
string		 Yes The trade name for this service contract.
deductible
number		 Yes Deductible amount per repair the purchaser is responsible for paying out of pocket.
personalized_url
string		 Yes Direct link to this particular plan/deductible (bypasses animation and opens whitelabel page with this plan selected).

Sample JSON Response

{
    "request_uuid": "749f36e2-3e51-4e1c-91aa-b2606d2616ed",
    "vendor_customer_id": "ABC12345",
    "vin": "JTMRFREV1JJ192877",
    "promo": "RYRWKKJ1O",
    "mileage": 36001,
    "state_id": "WV",
    "personalized_url": "https://api-testing-website.demo.cuvrd.com/personalized-offer?promo=RYRWKKJ1O&signature=713fd62663543ecf85d1c0f76ba78fffdf3d361a",
    "offers": [
        {
            "productRateIdHash": "931a088e4cf84bb200ad9f70227ece271258c6a1a7dcd44a03b4fd51ef4df848",
            "monthlySubscription": 19.99,
            "registrationFee": 49.99,
            "plan": "Superb Coverage",
            "deductible": 2000,
            "personalized_url": "https://api-testing-website.demo.cuvrd.com/personalized-offer?promo=OYRWKWJ0O&signature=d093feca069a5f60b3146d1ccb3e94cd88b05453&deductible=2000"
        },
        {
            "productRateIdHash": "6cecea8ef57f361d75bb92c1922b2e8901fba249130a7097c192c4e361c608c6",
            "monthlySubscription": 23.99,
            "registrationFee": 49.99,
            "plan": "Superb Coverage",
            "deductible": 1000,
            "personalized_url": "https://api-testing-website.demo.cuvrd.com/personalized-offer?promo=OYRWKWJ0O&signature=d093feca069a5f60b3146d1ccb3e94cd88b05453&deductible=1000"
        },
        {
            "productRateIdHash": "91c04051ef408d01f129e51783c99be8e4e36964443c711b6b1d6ae1224be53a",
            "monthlySubscription": 28.99,
            "registrationFee": 49.99,
            "plan": "Superb Coverage",
            "deductible": 500,
            "personalized_url": "https://api-testing-website.demo.cuvrd.com/personalized-offer?promo=OYRWKWJ0O&signature=d093feca069a5f60b3146d1ccb3e94cd88b05453&deductible=500"
        },
        {
            "productRateIdHash": "563d8d8c18ee481adfa5d2f29140be663492e938d52339734957c9184d8016d3",
            "monthlySubscription": 37.99,
            "registrationFee": 49.99,
            "plan": "Superb Coverage",
            "deductible": 100,
            "personalized_url": "https://api-testing-website.demo.cuvrd.com/personalized-offer?promo=OYRWKWJ0O&signature=d093feca069a5f60b3146d1ccb3e94cd88b05453&deductible=100"
        }
    ],
    "year": 2018,
    "make": "TOYOTA",
    "model": "RAV4",
    "series": "RAV4 ADVENTURE/XLE AWD",
    "no_plans_available": false,
    "vehicle_match": true,
    "precise_mileage": true,
    "estimated_pricing": false,
    "lowest_price": 19.99,
    "lowest_price_plan_hash": "931a088e4cf84bb200ad7f70227ece271258c6a1a7dcd44a03b1fd51ef4df848",
    "expires": 1690911501,
    "first_name": "Buddy",
    "last_name": "DuBuque",
    "email": "info@cuvrd.com",
    "phone": "8889991212",
    "address": "123 Any Street",
    "address_2": null,
    "city": "Norwichville",
    "zip": "01234",
    "covered_parts_url": "https://api.demo.cuvrd.com/api/vendor/get-covered-parts/931a088e4cf84bb200ad7f70227ece271258c6a1a7dcd44a03b4fd51ef4df848?apiKey=CV.KbHvHnUrPUs1UcPuep.OFwBG24zLxRudK61Sy"
}

Price Request Response Schema

  {
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Single Vehicle Subscription Vendor API - Price response",
  "description": "Subscription contract price response schema.",
  "properties": {
    "error": {
      "type": "string",
      "description": "A clear-text description of the error that has occurred.",
      "example": "Provided API key is invalid"
    },
    "request_uuid": {
      "type": "string",
      "description": "Our UID for this request",
      "example": "749f36e2-3e51-4e1c-91aa-b2606d2616ed"
    },
    "vendor_customer_id": {
      "type": "string",
      "description": "Your UID for this customer.  Also passed in personalized_url for analytics purposes.",
      "example": "vendor_customer_id"
    },
    "vin": {
      "type": "string",
      "minLength": 17,
      "maxLength": 17,
      "description": "The VIN for this vehicle. If no VIN was submitted, we will return a masked VIN with asterisks in positions 9 and 11-17.",
      "example": "JTMRFREV1JJ192877"
    },
    "promo": {
      "type": "string",
      "minLength": 10,
      "maxLength": 10,
      "description": "The promo code for this particular pricing offer. This code can be entered manually in our webisite in leiu of the customer's vehicle year, make, and model. Also passed in personalized_url",
      "example": "RYRWKKJ1O"
    },
    "mileage": {
      "type": "integer",
      "description": "Current mileage on this vehicle",
      "example": 36001
    },
    "state_id": {
      "type": "string",
      "enum": ["AL","AK","AZ","AR","CA","CO","CT","DC","DE","FL","GA","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","RI","SC","SD","TN","TX","UT","VT","VA","WA","WV","WI","WY"],
      "maxLength": 2,
      "description": "Customer's 2 letter state of residence code, all caps - required to offer coverage based on state restrictions."
      },
    "personalized_url": {
      "type": "string",
      "description": "Direct link to your whitelabel website that provides pricing for this customer/vehicle",
      "example": "https://api-testing-website.demo.cuvrd.com/personalized-offer?promo=RYRWKKJ1O&customerId=ABC12345&signature=713fd62663543ecf85d1c0f76ba78fffdf3d361a"
    },
    "offers": {
      "type": "array",
      "description": "Array comprised of available plans for this vehicle",
      "additionalItems": true,
      "items": {
        "type": "object",
        "description": "Available list of subscription service contracts",
        "required": [
          "productRateIdHash",
          "monthlySubscription",
          "registrationFee",
          "plan",
          "deductible"
        ],
        "properties": {
          "productRateIdHash": {
            "type": "string",
            "minLength": 64,
            "maxLength": 64,
            "description": "64 character alphanumeric id for this specific service contract/deductible combination.",
            "example": "931a088e4cf84bb200ad9f70227ece271258c6a1a7dcd44a03b4fd51ef4df848"
          },
          "monthlySubscription": {
            "type": "number",
            "description": "Subscription amount paid monthly starting no sooner than 30 days from the purchase date.",
            "example": 19.99
          },
          "registrationFee": {
            "type": "number",
            "description": "Amount due at the time of purchase.",
            "example": 49.99
          },
          "plan": {
            "type": "string",
            "description": "The trade name for this service contract",
            "example": "Cuvrd Superb Coverage"
          },
          "deductible": {
            "type": "number",
            "description": "Deductible amount per repair the purchaser is responsible for paying out of pocket.",
            "example": 100
          }
        },
        "additionalProperties": true
      }
    },
    "year": {
      "type": "string",
      "minLength": 4,
      "maxLength": 4,
      "description": "Vehicle year decoded from VIN",
      "example": "2018"
    },
    "make": {
      "type": "string",
      "description": "Vehicle make decoded from VIN",
      "example": "TOYOTA"
    },
    "model": {
      "type": "string",
      "description": "Vehicle model decoded from VIN",
      "example": "CAMRY"
    },
    "series": {
      "type": "string",
      "description": "Extended vehicle model information decoded from VIN",
      "example": "CAMRY XLE"
    },
    "no_plans_available": {
      "type": "boolean",
      "description": "true = no coverage available for this vehicle",
    },
    "vehicle_match": {
      "type": "boolean",
      "description": "true = an exact match was found in our database for this vin or year/make/model. false = we were not able to perfectly match this vehicle with an entry in our database-we are returning the best possible match",
    },
    "precise_mileage": {
      "type": "boolean",
      "description": "true = mileage was passed in the request and pricing was based on that mileage. false = mileage was not passed, current mileage was estimated based on vehicle age.",
    },
    "estimated_pricing": {
      "type": "boolean",
      "description": "true = pricing for this vehicle is estimated due to precise_mileage = false or vehicle_match = false.",
    },
    "lowest_price": {
      "type": "number",
      "description": "lowest monthly subscription price returned in the offers array.",
      "example": 19.99
    },
    "lowest_price_plan_hash": {
      "type": "string",
      "minLength": 64,
      "maxLength": 64,
      "description": "64 character alphanumeric id for the lowest price service contract/deductible combination returned in the offers array.",
      "example": "931a088e4cf84bb200ad9f70227ece271258c6a1a7dcd44a03b4fd51ef4df848"
    },
    "expires": {
      "type": "integer",
      "description": "UNIX/Epoch time stamp representing the time this personalized link expires.",
      "example": 1690911501
    },
    "first_name": {
      "type": "string",
      "maxLength": 20,
      "description": "Customer's last name"
      },
    "last_name": {
      "type": "string",
      "maxLength": 20,
      "description": "Customer's last name"
      },
   "email": {
      "type": "string",
      "maxLength": 30,
      "description": "Customer's email address"
      },
    "phone": {
      "type": "string",
      "minLength": 10,
      "maxLength": 10,
      "description": "Customer's 10 digit phone number - digits only",
      "example": "3125551212"
      },
    "address": {
      "type": "string",
      "maxLength": 30,
      "description": "Customer's street address"
      },
    "address_2": {
      "type": "string",
      "maxLength": 30,
      "description": "Apt, Unit, etc."
      },
    "city": {
      "type": "string",
      "maxLength": 20,
      "description": "Customer's city"
      },
    "zip": {
      "type": "string",
      "minLength": 5,
      "maxLength": 5,
      "description": "Customer's 5 digit zip code",
      "example": "02184"
      }
  },
  "additionalProperties": true
}

Errors

Response Parameters

Key/Type Required Description
error
string		 No A clear-text description of the error that has occurred.

Sample JSON Response

{
    "error": "Provided API key is invalid"
}