Cuvrd REST API

Term VSC API - v1

Current Version

1.5.0, Updated July 14, 2023

1.5.0: Added logic for retrieving state sales tax rates and reporting sales tax collected as well as reporting any state-mandated profit caps.

Overview

The Cuvrd Term VSC API is a two-step process.

Our goal, especially with the initial Price Request step, is to make it as simple as possible for your users to get the universe of plans and pricing available for your customer's vehicle. We only ask for the vehicle's VIN, current mileage, and the purchaser's state (along with your API credentials) to price out our plans.

The second step, where the contract is booked on our side, requires that you send back tokens for the pricing request and the chosen plan provided to you in step 1.

In the end, you'll get a summary of the contract you booked as well as a link to your customer's full service contract document. We keep these documents stored on our side, and you can return in the future to download a copy if you need it.

Here's a summary of the two steps:

Step 1: Price Request.

A bare minimum of your customer's vehicle data is passed to us (vin, mileage, and purchaser's state), and the API responds with one or more coverage plans that are available for the vehicle ranked by value to the consumer in ascending order with the best value option first (best value = 1).

Step 2: Purchase Request.

Response data from Step 1 is passed, including additional coverage options that are available to the consumer for a surcharge, and the API responds, with a results file containing data for the VSC purchased and a link to a PDF copy of the purchaser's service contract.

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, as well as providing the end-user with clear messages regarding plan availability.

In some cases, the vehicle may not be eligible for due to age, purchaser state of residence, or vehicle mileage. API Error responses will aid your end users to correct possible input mistakes/typos such as incorrect mileage or VIN.

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 if you receive anything other than status 200.

API URL

The Cuvrd production API is located at:

https://restapi.cuvrd.com

The Cuvrd testing API is located at:

https://restapi-testing.cuvrd.com

Authentication

Credentials are passed to the API in the body of the request. There is no need to pass authentication credentials as a header.

Testing Credentials

Testing Vendor ID:

22112

Testing API Key:

396e7b13501d5286b166695081cfd2d8d40019aa

Documentation

Step 1: Price Request

Step 1 API Endpoint:

POST /term_vsc/v1/price_request/

Header:

Content-Type: application/json

Body Parameters

Key/Type Required Description
vendor_id
integer		 Yes The vendor ID provided by Cuvrd.
api_key
string		 Yes Secret alphanumeric string provided by Cuvrd.
vin
string		 Yes 17 character alphanumeric VIN of the vehicle.
mileage
integer		 Yes The vehicle's current mileage.
monthly_mileage
integer		 No Average miles per month the vehicle is driven.
state
string		 Yes Purchaser's 2 letter state of residence code, all caps - required to offer coverage based on state restrictions.

cURL example

curl --location --request POST 'https://restapi.cuvrd.com/term_vsc/v1/price_request/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "vendor_id": 22112,
    "api_key": "396e7b13501d5286b166695081cfd2d8d40019aa",
    "vin": "3C63R3GL3JG236800",
    "mileage": 40001,
    "monthly_mileage": 0,
    "state": "MT"
}'

Sample JSON

{
  "vendor_id": 22112,
  "api_key": "396e7b13501d5286b166695081cfd2d8d40019aa",
  "vin": "3C63R3GL3JG236800",
  "mileage": 40001,
  "monthly_mileage": 0,
  "state": "MT"
}

Price Request Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Term Contract Vendor API - Price request",
  "description": "Term contract price request schema.",
  "required": [
    "vendor_id",
    "api_key",
    "vin",
    "mileage"
  ],
  "properties": {
    "vendor_id": {
      "type": "integer",
      "minimum": 20000,
      "maximum": 99999,
      "description": "The vendor ID provided by Cuvrd.",
      "example": 22112    },
    "api_key": {
      "type": "string",
      "minLength": 40,
      "maxLength": 40,
      "description": "40 character alphanumeric string provide by Cuvrd.",
      "example": "396e7b13501d5286b166695081cfd2d8d40019aa"
    },
    "vin": {
      "type": "string",
      "minLength": 17,
      "maxLength": 17,
      "description": "17 character alphanumeric VIN of the vehicle",
      "example": "3C63R3GL3JG236800"
    },
    "mileage": {
      "type": "integer",
      "minimum": 1,
      "maximum": 999999,
      "description": "The vehicle's current mileage"
    },
    "monthly_mileage": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999999,
      "description": "Average miles per month the vehicle is driven. Optional."
    },
    "state": {
      "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": "Purchaser's 2 letter state of residence code, all caps - required to offer coverage based on state restrictions."
    }
  }
}

Step 1: Price Request Response

Response Parameters

Key/Type Required Description
api_name
string		 Yes Name of this API.
version
string		 Yes Semantic version of this API.
step
integer		 Yes The response step in this API's sequence.
success
integer		 Yes Flag to indicate a successful request and response. Success = 1, Fail = 0.
error_code
integer		 Yes 0 if successful, integer > 0 if failure. See appendix for a list of error codes.
response_message
string		 Yes Success or full text response of the error_code field.
request_date_time
string		 Yes Date-time this request was processed.
request_token
string		 No 40 character alphanumeric id for this request - must be returned in next step.
vin
string		 No 17 character vehicle identification number sent in request.
vehicle_year
string		 No Vehicle year decoded from VIN.
vehicle_make
string		 No Vehicle make decoded from VIN.
vehicle_model
string		 No Vehicle model decoded from VIN.
vehicle_series
string		 No Extended vehicle model information decoded from VIN.
state_tax_rate
number		 No New Decimal tax rate for this state.
state_profit_cap
number		 No New Profit cap for this state - 0.00 if no cap.
available_plans
array		 No Array comprised of an ordered set of service contracts available for this vehicle.
leinholders
array		 No Array of leinholders provided by the vendor. This is useful for creating a vendor-side dropdown selector of leinholders supplied to Cuvrd. Supplying a list of leinholders in advance is not required to attach a leinholder to a contract. Leinholder details can be also be submitted manually in Step 2.

available_plans  Parameters

Key/Type Required Description
rank
integer		 Yes Rank of this service contract based on coverage, value, miles traveled, contract length, etc. 1 = best.
product_id
string		 Yes 40 character alphanumeric id for this specific service contract - the product_id for the plan purchaed must be returned in next step.
total_vendor_cost
number		 Yes Wholesale cost of this service contract to the vendor. This is the amount that must be remitted to the administrator..
program_name
string		 Yes The trade name for this service contract.
plan_level
string		 Yes Description of the coverage level of this service contract (Platinum, Gold, Silver, etc.).
plan_coverage_type
string		 Yes Short code for the type of coverage provided (VSC, GAP, PPM, etc.).
wait_miles
integer		 Yes Number of miles driven after the service contract has been purchased before going into service; typically 1000 miles.
wait_days
integer		 Yes Number of days after the service contract has been purchased before going into service; typically 30 days.
deductible
number		 Yes Deductible amount per repair the purchaser is responsible for paying out of pocket.
program_term_months
integer		 Yes Length in months of this plan.
program_miles
integer		 Yes Length in miles of this service contract.
add_on_miles
integer		 Yes 0 = coverage ends when vehicle odometer reaches program_miles value, 1 = coverage ends when traveled miles equals program_miles.
net_covered_miles
integer		 Yes The net number of miles that this service contract will be in effect.
expiration_miles
integer		 Yes The contract coverage will end when the vehicle odometer reaches this value.
options
array		 No Array of additional coverages that are either included in this plan or are available to purchase for the stated cost.

options  Parameters

Key/Type Required Description
code
string		 Yes The short code for this specific option. ["elr", "av", "emi", "com", "lft", "snp"]
description
string		 Yes Clear text description of this specific optional coverage.
included
integer		 No Set to 1 if it is included in this service contract. Not present if not included.
available
integer		 No Set to 1 if this optional coverage is available for purchase at the amount listed in the cost field. This value will be added to the total_vendor_cost if selected during purchase. Not present if coverage is included in this plan.
cost
number		 No The additional upcharge to add this option to the service contract. Not present if included.

leinholder  Parameters

Key/Type Required Description
leinholder_id
integer		 Yes Internal code for this leinholder. Must return this code to attach this leinholder as a "pre-selected leinholder" to a serivce contract purchase.
leinholder_name
string		 Yes Clear text name of the leinholder for display purposes.

Sample JSON Response

{
  "api_name": "Cuvrd Term Contract Vendor API",
  "version": "1.5.0",
  "step": 1,
  "success": 1,
  "error_code": 0,
  "response_message": "Request successful.",
  "request_date_time": "2020-01-01 16:45:20",
  "request_token": "b08d49de44e0548cf482a2361fb76cdc2ad015b8",
  "vin": "3C63R3GL3JG236800",
  "vehicle_year": "2018",
  "vehicle_make": "RAM",
  "vehicle_model": "3500",
  "vehicle_series": "3500 ST",
  "state_tax_rate": 0.03500000,
  "state_profit_cap": 2000.00,
  "available_plans": [
    {
      "rank": 1,
      "product_id": "7b5f0c1daaa0f1abb61562f380d2f26640547db6",
      "total_vendor_cost": 1638,
      "program_name": "Horizon",
      "plan_level": "Diamond",
      "plan_coverage_type": "VSC",
      "wait_days": 30,
      "wait_miles": 1000,
      "deductible": 50,
      "program_term_months": 72,
      "program_miles": 100000,
      "add_on_miles": 0,
      "net_covered_miles": 59999,
      "expiration_miles": 100000,
      "options": [
        {
          "code": "elr",
          "description": "Enhanced Labor",
          "included": 1
        },
        {
          "code": "av",
          "description": "Technology Group Coverage",
          "included": 1
        },
        {
          "code": "emi",
          "description": "Emissions Coverage",
          "included": 1
        },
        {
          "code": "com",
          "description": "Light Commercial Vehicle",
          "available": 1,
          "cost": 300
        }
      ]
    },
    {
      "rank": 2,
      "product_id": "78c51c0c5baf8e8af9c027f93d287833ac4784c3",
      "total_vendor_cost": 1467,
      "program_name": "Secure Advantage",
      "plan_level": "Platinum",
      "plan_coverage_type": "VSC",
      "wait_days": 30,
      "wait_miles": 1000,
      "deductible": 50,
      "program_term_months": 72,
      "program_miles": 100000,
      "add_on_miles": 0,
      "net_covered_miles": 59999,
      "expiration_miles": 100000,
      "options": [
        {
          "code": "elr",
          "description": "Enhanced Labor",
          "included": 1
        },
        {
          "code": "av",
          "description": "Technology Group Coverage",
          "available": 1,
          "cost": 275
        },
        {
          "code": "emi",
          "description": "Emissions Coverage",
          "available": 1,
          "cost": 200
        },
        {
          "code": "com",
          "description": "Light Commercial Vehicle",
          "available": 1,
          "cost": 300
        }
      ]
    }
  ],
  "leinholders": [
    {
      "leinholder_id": 5001,
      "leinholder_name": "American National Bank"
    },
    {
      "leinholder_id": 5013,
      "leinholder_name": "JP Morgan Chase Bank"
    }
  ]
}

Price Request Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Term Contract Vendor API - Price request response",
  "description": "Term contract price request response schema.",
  "required": [
    "api_name",
    "version",
    "step",
    "success",
    "error_code",
    "response_message",
    "request_date_time"
  ],
  "properties": {
    "api_name": {
      "type": "string",
      "description": "Name of this API.",
      "example": "Cuvrd Term Contract Vendor API"
    },
    "version": {
      "type": "string",
      "description": "Semantic version of this API.",
      "example": "1.5.0"
    },
    "step": {
      "type": "integer",
      "description": "The response step in this API's sequence.",
      "example": 1
    },
    "success": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Flag to indicate a successful request and response. Success = 1, Fail = 0",
      "example": 1
    },
    "error_code": {
      "type": "integer",
      "description": "0 if successful, integer > 0 if failure. See appendix for a list of error codes.",
      "example": 1
    },
    "response_message": {
      "type": "string",
      "description": "Success or full text response of the error_code field.",
      "example": "Request successful."
    },
    "request_date_time": {
      "type": "string",
      "description": "date-time this request was processed",
      "example": "2021-01-01 12:34:26"
    },
    "request_token": {
      "type": "string",
      "minLength": 40,
      "maxLength": 40,
      "description": "40 character alphanumeric id for this request - must be returned in next step",
      "example": "d5dedefa4960914af949b36414009b2ebeaceee0"
    },
    "vin": {
      "type": "string",
      "minLength": 17,
      "maxLength": 17,
      "description": "17 character vehicle identification number sent in request",
      "example": "3R63R3GL3JG236800"
    },
    "vehicle_year": {
      "type": "string",
      "minLength": 4,
      "maxLength": 4,
      "description": "Vehicle year decoded from VIN",
      "example": "2018"
    },
    "vehicle_make": {
      "type": "string",
      "description": "Vehicle make decoded from VIN",
      "example": "TOYOTA"
    },
    "vehicle_model": {
      "type": "string",
      "description": "Vehicle model decoded from VIN",
      "example": "CAMRY"
    },
    "vehicle_series": {
      "type": "string",
      "description": "Extended vehicle model information decoded from VIN",
      "example": "CAMRY XLE"
    },
    "state_tax_rate": {
      "type": "number",
      "description": "Decimal tax rate for this state",
      "example": 0.03500000
    },
    "state_profit_cap": {
      "type": "number",
      "description": "Profit cap for this state - 0.00 if no cap",
      "example": 2000.00
    },
    "available_plans": {
      "type": "array",
      "description": "Array comprised of an ordered set of service contracts available for this vehicle",
      "additionalItems": true,
      "items": {
        "type": "object",
        "description": "Available list of service contracts",
        "required": [
          "rank",
          "product_id",
          "total_vendor_cost",
          "program_name",
          "plan_level",
          "plan_coverage_type",
          "wait_days",
          "wait_miles",
          "deductible",
          "program_term_months",
          "program_miles",
          "add_on_miles",
          "net_covered_miles",
          "expiration_miles"
        ],
        "properties": {
          "rank": {
            "type": "integer",
            "minimum": 1,
            "description": "Rank of this service contract based on coverage, value, miles traveled, contract length, etc. 1 = best",
            "example": 1
          },
          "product_id": {
            "type": "string",
            "minLength": 40,
            "maxLength": 40,
            "description": "40 character alphanumeric id for this specific service contract - the product_id for the plan purchaed must be returned in next step",
            "example": "7b5f0c1daaa0f1abb61562f380d2f26640547db6"
          },
          "total_vendor_cost": {
            "type": "number",
            "description": "Wholesale cost of this service contract to the vendor. This is the amount that must be remitted to the administrator.",
            "example": 652
          },
          "program_name": {
            "type": "string",
            "description": "The trade name for this service contract",
            "example": "Horizon"
          },
          "plan_level": 
            {
              "type": "string",
              "description": "Description of the coverage level of this service contract (Platinum, Gold, Silver, etc.)",
              "example": "GOLD"
            },
            "plan_coverage_type":
            {
              "type": "string",
              "description": "Short code for the type of coverage provided (VSC, GAP, PPM, etc.)",
              "example": "VSC"
            }
          ,
          "wait_days": {
            "type": "integer",
            "description": "Number of days after the service contract has been purchased before going into service--typically 30 days",
            "example": 30
          },
          "wait_miles": {
            "type": "integer",
            "description": "Number of miles driven after the service contract has been purchased before going into service--typically 1000 miles.",
            "example": 1000
          },
          "deductible": {
            "type": "number",
            "description": "Deductible amount per repair the purchaser is responsible for paying out of pocket.",
            "example": 100
          },
          "program_term_months": {
            "type": "integer",
            "description": "Length in months of this plan",
            "example": 48
          },
          "program_miles": {
            "type": "integer",
            "description": "Length in miles of this service contract",
            "example": 48000
          },
          "add_on_miles": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "0 = coverage ends when *vehicle odometer* reaches program_miles value, 1 = coverage ends when *traveled miles* equals program_miles",
            "example": 1
          },
          "net_covered_miles": {
            "type": "integer",
            "description": "The net number of miles that this service contract will be in effect",
            "example": 48000
          },
          "expiration_miles": {
            "type": "integer",
            "description": "The contract coverage will end when the vehicle odometer reaches this value",
            "example": 97465
          },
          "options": {
            "type": "array",
            "description": "Array of additional coverages that are either included in this plan or are available to purchase for the stated cost.",
            "additionalItems": true,
            "items": {
              "type": "object",
              "description": "Additional or included coverages",
              "properties": {
                "code": {
                  "type": "string",
                  "enum": [
                    "elr",
                    "av",
                    "emi",
                    "com",
                    "lft",
                    "snp"
                  ],
                  "description": "The short code for this specific option. See appendix for optional coverage types.",
                  "example": "elr"
                },
                "description": {
                  "type": "string",
                  "description": "Clear text description of this coverage",
                  "example": "Enhanced Labor"
                },
                "included": {
                  "type": "integer",
                  "enum": [
                    1
                  ],
                  "description": "Set to 1 if it is included in this service contract. Not present if not included",
                  "example": 1
                },
                "available": {
                  "type": "integer",
                  "enum": [
                    1
                  ],
                  "description": "Set to 1 if this optional coverage is available for purchase at the amount listed in the cost field. This value will be added to the total_vendor_cost if selected during purchase. Not present if coverage is included in this plan.",
                  "example": 1
                },
                "cost": {
                  "type": "number",
                  "description": "The additional upcharge to add this option to the service contract. Not present if included.",
                  "example": 250
                }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      }
    },
    "leinholders": {
      "type": "array",
      "description": "Array of leinholders provided by then vendor.",
      "additionalItems": true,
      "items": {
        "type": "object",
        "description": "Specific leinholder codes and names.",
        "required": [
          "leinholder_id",
          "leinholder_name"
        ],
        "properties": {
          "leinholder_id": {
            "type": "integer",
            "description": "Internal code for this leinholder - must return this code to attach this leinholder to a serivce contract purchase.",
            "example": 5001
          },
          "leinholder_name": {
            "type": "string",
            "description": "Clear text name of the leinholder for display purposes",
            "example": "American National Bank"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

Step 2: Purchase Request

Step 2 API Endpoint:

POST /term_vsc/v1/purchase/

Header:

Content-Type: application/json

Body Parameters

Key/Type Required Description
vendor_id
integer		 Yes The vendor ID provided by Cuvrd.
api_key
string		 Yes Secret alphanumeric string provided by Cuvrd.
vin
string		 Yes 17 character alphanumeric VIN of the vehicle.
mileage
integer		 Yes The vehicle's current mileage.
request_token
string		 Yes 40 character alphanumeric request_token provided in pricing response.
product_id
string		 Yes 40 character alphanumeric product_id of the plan chosen from the response.
contract_purchase_price
number		 Yes Total pre-tax retail price paid by the customer for this service contract. Integer and decimal values accepted. Must be greater than the total vendor cost. Do not include sales taxes in this amount.
tax_collected
number		 No New Sales tax collected for this VSC.
contract_purchase_date
string		 Yes The official purchase date of this service contract, ANSI date formatted string.
vehicle_value
number		 No Current value of this vehicle. integer and decimal values accepted.
app_id
string		 No Application ID of the customer/loan in the submitting partner's system. Passing this value is useful for searching for results and matching records from reports.
purchaser
object		 Yes An object containing the name(s)/address/contact info of the Purchaser.
leinholder
integer		 No leinholder_id of the leinholder chosen from the results response. Optional if supplying manual leinholder info, no leinholder, or paid in full.
leinholder_ext
object		 No Optional method to allow submitting partner to manually pass leinholder information.
options
object		 No Object for passing the purchase of optional coverages.

purchaser  Parameters

Key/Type Required Description
first_name
string		 Yes Purchaser's first name.
last_name
string		 Yes Purchaser's last name.
first_name_2
string		 No Co-purchaser's first name if applicable.
last_name_2
string		 No Co-purchaser's last name if applicable.
address_1
string		 Yes Purchaser's street address.
address_2
string		 No Apt, Unit, etc.
city
string		 Yes Purchaser's city.
state
string		 Yes Purchaser's 2 letter state code, all caps - Important: Must match state submitted in step 1. The API will throw an error if the state does not match the state reported in the initial pricing request.
zip
string		 Yes Purchaser's 5 digit zip code.
phone
string		 Yes Purchaser's 10 digit phone number - digits only. (example: 3125551212)
email
string		 No Purchaser's email address.

leinholder_ext  Parameters

Key/Type Required Description
leinholder_ext_code
string		 Yes Submitting Partner's leinholder code/ID.
leinholder_name
string		 Yes Leinholder legal name.
leinholder_name
string		 Yes Clear text name of the leinholder for display purposes.
leinholder_address_1
string		 Yes First line of leinholder address, does not need to be a street address.
leinholder_address_2
string		 No Second line of leinholder address, does not need to be a street address.
leinholder_city
string		 Yes Leinholder city.
leinholder_state
string		 Yes Leinholder's 2 letter state code, all caps.
leinholder_zip
string		 Yes Leinholder's 5 digit zip code.
leinholder_phone
string		 Yes Leinholder's 10 digit phone number - digits only. (example: 3125551212)

options  Parameters

Notes for options object:

– All values are enum: [0,1]

– For all keys: Send [1] if the customer wishes to purchase this optional additional coverage. Send [0] OR do not include this key to decline this coverage option.

– Not transmitting a key = sending [0] for the element.

– These values will be ignored if the coverage is a) already included or b) not available on the chosen plan

Key/Type Required Description
elr
integer		 No Enhanced Labor Option.
1 = add optional coverage
0 = decline optional coverage
av
integer		 No Technology Group Coverage Option.
1 = add optional coverage
0 = decline optional coverage
emi
integer		 No Emissions Coverage Option.
1 = add optional coverage
0 = decline optional coverage
lft
integer		 No Dealer Installed Lift Kit Option.
1 = add optional coverage
0 = decline optional coverage
NOTE: This option has very limited availability.
com
integer		 No Light Commercial Vehicle Option.
1 = add optional coverage
0 = decline optional coverage
snp
integer		 No Snow Plow Option.
1 = add optional coverage
0 = decline optional coverage
NOTE: This option has very limited availability.

cURL example

curl --location --request POST 'https://restapi.cuvrd.com/term_vsc/v1/purchase/' \
--header 'Content-Type: application/json' \
--data-raw '{
  "vendor_id": 22112,
  "api_key": "396e7b13501d5286b166695081cfd2d8d40019aa",
  "vin": "2FMDK4JC0EBA13750",
  "mileage": 42001,
  "request_token": "876209c9eac1114e88d3fbe2222d769acc4bf57b",
  "product_id": "7e22228e9e529352ca1c024444c79f9bd7d5ac8c", 
  "contract_purchase_price": 4200.00,
  "tax_collected": 128.00,
  "contract_purchase_date": "2022-02-01",
  "vehicle_value": 22000.00,
  "app_id": "MYappID213",
  "purchaser": {
    "first_name": "John",
    "last_name": "Doe",
    "first_name_2": "Jane",
    "last_name_2": "Doe",
    "address_1": "111 N. Any Street",
    "address_2": "Unit A",
    "city": "S. Anytown",
    "state": "SC",
    "zip": "02184",
    "phone": "8885551212",
    "email": "jd@example.com"
  },
  "leinholder_ext": {
    "leinholder_ext_code": "A20032",
    "leinholder_name": "Federal Vehicle Loans Inc.",
    "leinholder_address_1": "111 N. Lein Street",
    "leinholder_address_2": "Suite 325",
    "leinholder_city": "More Money",
    "leinholder_state": "MO",
    "leinholder_zip": "02184",
    "leinholder_phone": "8885551212"
  },
  "options": {
    "elr": 1,
    "emi": 1,
    "com": 0,
    "snp": 0
  }
}'

Sample JSON

{
  "vendor_id": 22112,
  "api_key": "396e7b13501d5286b166695081cfd2d8d40019aa",
  "vin": "2FMDK4JC0EBA13750",
  "mileage": 42001,
  "request_token": "876209c9eac5324e88d3fbe3909d769acc4bf57b",
  "product_id": "7e55638e9e529352ca1c02e418c79f9bd7d5ac8c", 
  "contract_purchase_price": 4200.00,
  "tax_collected": 128.00,
  "contract_purchase_date": "2022-02-01",
  "vehicle_value": 22000.00,
  "app_id": "MYappID213",
  "purchaser": {
    "first_name": "John",
    "last_name": "Doe",
    "first_name_2": "Jane",
    "last_name_2": "Doe",
    "address_1": "111 N. Any Street",
    "address_2": "Unit A",
    "city": "S. Anytown",
    "state": "SC",
    "zip": "02184",
    "phone": "8885551212",
    "email": "jd@example.com"
  },
  "leinholder_ext": {
    "leinholder_ext_code": "A20032",
    "leinholder_name": "Federal Vehicle Loans Inc.",
    "leinholder_address_1": "111 N. Lein Street",
    "leinholder_address_2": "Suite 325",
    "leinholder_city": "More Money",
    "leinholder_state": "MO",
    "leinholder_zip": "02184",
    "leinholder_phone": "8885551212"
  },
  "options": {
    "elr": 1,
    "emi": 1,
    "com": 0,
    "snp": 0
  }
}

Purchase Request Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Term Contract Vendor API - Purchase request",
  "properties": {
    "vendor_id": {
      "type": "integer",
      "minimum": 20000,
      "maximum": 99999,
      "description": "The vendor ID provided by Cuvrd.",
      "example": 20000
    },
    "api_key": {
      "type": "string",
      "minLength": 40,
      "maxLength": 40,
      "description": "40 character alphanumeric string provide by Cuvrd",
      "example": "6f338d4c440d6f845746e98fdd67d1ec0fa12888"
    },
    "vin": {
      "type": "string",
      "minLength": 17,
      "maxLength": 17,
      "description": "17 alphanumeric VIN of the vehicle previously sent in price reqest",
      "example": "3C63R3GL3JG236800"
    },
    "mileage": {
      "type": "integer",
      "minimum": 1,
      "maximum": 999999,
      "description": "The vehicle's current mileage"
    },
    "request_token": {
      "type": "string",
      "minLength": 40,
      "maxLength": 40,
      "description": "40 character alphanumeric request_token provided in pricing response",
      "example": "6f338d4c440d6f845746e98fdd67d1ec0fa12888"
    },
    "product_id": {
      "type": "string",
      "minLength": 40,
      "maxLength": 40,
      "description": "40 character alphanumeric product_id of the plan chosen from the response",
      "example": "7b5f0c1daaa0f1abb61562f380d2f26640547db6"
    },
    "contract_purchase_price": {
      "type": "number",
      "description": "Total pre-tax retail price paid by the customer for this service contract. DO NOT include sales tax in this amount. integer and decimal values accepted",
      "example": 3200
    },
    "tax_collected": {
      "type": "number",
      "description": "Sales tax collected for this VSC. integer and decimal values accepted",
      "example": 128
    },
    "contract_purchase_date": {
      "type": "string",
      "format": "date",
      "description": "The official purchase date of this service contract, ANSI date formatted string",
      "example": "2022-01-01"
    },
    "vehicle_value": {
      "type": "number",
      "description": "Current value of this vehicle. integer and decimal values accepted - OPTIONAL",
      "example": 17000
    },
    "app_id": {
      "type": "string",
      "description": "Application ID of the customer/loan in the submitting partner's system. Passing this value is useful for searching for results and matching records from reports.",
      "example": "ABC1234567"
    },
    "purchaser": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "maxLength": 20,
          "description": "Purchaser's first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 20,
          "description": "Purchaser's last name"
        },
        "first_name_2": {
          "type": "string",
          "maxLength": 20,
          "description": "OPTIONAL - Co-purchaser's first name if applicable"
        },
        "last_name_2": {
          "type": "string",
          "maxLength": 20,
          "description": "OPTIONAL - Co-purchaser's last name if applicable"
        },
        "address_1": {
          "type": "string",
          "maxLength": 30,
          "description": "Purchaser's street address"
        },
        "address_2": {
          "type": "string",
          "maxLength": 30,
          "description": "OPTIONAL - Apt, Unit, etc."
        },
        "city": {
          "type": "string",
          "maxLength": 20,
          "description": "Purchaser's city"
        },
        "state": {
          "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": "Purchaser's 2 letter state code, all caps - *must match state submitted in step 1*"
        },
        "zip": {
          "type": "string",
          "minLength": 5,
          "maxLength": 5,
          "description": "Purchaser's 5 digit zip code",
          "example": "02184"
        },
        "phone": {
          "type": "string",
          "minLength": 10,
          "maxLength": 10,
          "description": "Purchaser's 10 digit phone number - digits only",
          "example": "3125551212"
        },
        "email": {
          "type": "string",
          "maxLength": 30,
          "description": "OPTIONAL - Purchaser's email address"
        }
      },
      "required": [
        "first_name",
        "last_name",
        "address_1",
        "city",
        "state",
        "zip",
        "phone"
      ]
    },
    "leinholder": {
      "type": "integer",
      "description": "leinholder_id of the leinholder chosen from the results response. Optional if no leinholder or paid in full"
    },
    "leinholder_ext": {
      "type": "object",
      "description": "Optional method to allow submitting partner to pass leinholder information",
      "properties": {
        "leinholder_ext_code": {
          "type": "string",
          "maxLength": 30,
          "description": "Submitting Partner's leinholder code/ID (Inbound)"
        },
        "leinholder_name": {
          "type": "string",
          "maxLength": 30,
          "description": "Leinholder Name"
        },
        "leinholder_address_1": {
          "type": "string",
          "description": "First line of leinholder address, does not need to be a street address"
        },
        "leinholder_address_2": {
          "type": "string",
          "maxLength": 30,
          "description": "Second line of leinholder address, does not need to be a street address"
        },
        "leinholder_city": {
          "type": "string",
          "maxLength": 30,
          "description": "Leinholder city"
        },
        "leinholder_state": {
          "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": "Leinholder's 2 letter state code, all caps"
        },
        "leinholder_zip": {
          "type": "string",
          "minLength": 5,
          "maxLength": 5,
          "description": "Leinholder's 5 digit zip code",
          "example": "02184"
        },
        "leinholder_phone": {
          "type": "string",
          "minLength": 10,
          "maxLength": 10,
          "description": "Leinholder's 10 digit phone number - digits only",
          "example": "3125551212"
        }
      },
      "options": {
        "type": "object",
        "properties": {
          "elr": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Enhanced Labor Option. Send [1] if the customer wishes to purchase this optional additional coverage. This value will be ignored if the coverage is a) already included or b) not available on this plan."
          },
          "av": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Technology Group Coverage Option.  Send [1] if the customer wishes to purchase this optional additional coverage. This value will be ignored if the coverage is a) already included or b) not available on this plan."
          },
          "emi": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Emissions Coverage Option.  Send [1] if the customer wishes to purchase this optional additional coverage. This value will be ignored if the coverage is a) already included or b) not available on this plan."
          },
          "lft": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Dealer Installed Lift Kit Option.  Send [1] if the customer wishes to purchase this optional additional coverage. This value will be ignored if the coverage is a) already included or b) not available on this plan. NOTE: this option has very limited availability."
          },
          "com": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Light Commercial Vehicle Option.  Send [1] if the customer wishes to purchase this optional additional coverage. This value will be ignored if the coverage is a) already included or b) not available on this plan."
          },
          "snp": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Snow Plow Option.  Send [1] if the customer wishes to purchase this optional additional coverage. This value will be ignored if the coverage is a) already included or b) not available on this plan. NOTE: this option has very limited availability."
          }
        },
        "required": []
      }
    },
    "required": [
      "vendor_id",
      "api_key",
      "vin",
      "mileage",
      "request_token",
      "product_id",
      "contract_purchase_price",
      "contract_purchase_date",
      "purchaser"
    ]
  }
}

Step 2: Purchase Request Response

Response Parameters

Key/Type Required Description
api_name
string		 Yes Name of this API.
version
string		 Yes Semantic version of this API.
step
integer		 Yes The response step in this API's sequence.
success
integer		 Yes Flag to indicate a successful request and response. Success = 1, Fail = 0.
error_code
integer		 Yes 0 if successful, integer > 0 if failure. See appendix for a list of error codes.
response_message
string		 Yes Success or full text response of the error_code field.
request_date_time
string		 Yes Date-time this request was processed.
vin
string		 No 17 character vehicle identification number sent in request.
vehicle_year
string		 No Vehicle year decoded from VIN.
vehicle_make
string		 No Vehicle make decoded from VIN.
vehicle_model
string		 No Vehicle model decoded from VIN.
vehicle_series
string		 No Extended vehicle model information decoded from VIN.
total_customer_cost
number		 No Pre-tax retail cost of this service contract to the customer.
tax_collected
number		 No New Sales tax collected for this VSC.
total_vendor_cost
number		 No Wholesale cost of this service contract to the vendor. This is the amount that must be remitted to the administrator.
vendor_markup
number		 No The amount of profit retained by the vendor. Comprised of total_customer_cost minus total_vendor_cost.
contract_purchase_date
string		 No The official purchase date of this service contract, ANSI date formatted string.
contract_id
string		 No The contract number/id assigned to this service contract.
program_name
string		 No The trade name for this service contract.
plan_level
string		 No Description of the coverage level of this service contract (Platinum, Gold, Silver, etc.).
new_or_used
string		 No Denotes new car coverage (expires when odometer reaches program miles) or used (expires when program miles are travelled from date of purchase).
wait_days
integer		 No Number of days after the service contract has been purchased before going into service. Typically 30 days.
wait_miles
integer		 No Number of miles driven after the service contract has been purchased before going into service. Typically 1000 miles.
deductible
number		 No Deductible amount per repair the purchaser is responsible for paying out of pocket.
program_term_months
integer		 No Length in months of this plan.
program_miles
integer		 No Length in miles of this service contract.
net_covered_miles
integer		 No The net number of miles that this service contract will be in effect.
expiration_miles
integer		 No The contract coverage will end when the covered vehicle's odometer reaches this value.
add_on_miles
integer		 No 0 = coverage ends when vehicle odometer reaches program_miles value, 1 = coverage ends when traveled miles equals program_miles.
options
array		 No Array of additional coverages that are either included in this plan or were purchased as an option.
purchaser
object		 No An object containing the name(s)/address/contact info of the Purchaser.
leinholder_id
string		 No leinholder_id of the leinholder chosen from the results response OR the leinholder_ext code manually supplied by the vendor.
leinholder_name
string		 No Clear text name of the leinholder for display purposes.
document_name
string		 No Name of the service contract document without the file extension.
document_extension
string		 No File extension of the service contract document (document_name + document_extension = full document name).
document_id
string		 No Unique identifier needed to obtain this document (in conjunction with the document name).
document_url
string		 No URL of the purchaser's service contract in PDF format.

options  Parameters

Key/Type Required Description
code
string		 Yes The short code for this specific option. ["elr", "av", "emi", "com", "lft", "snp"]
description
string		 Yes Clear text description of this specific optional coverage.

purchaser  Parameters

Key/Type Required Description
first_name
string		 Yes Purchaser's first name.
last_name
string		 Yes Purchaser's last name.
first_name_2
string		 No Co-purchaser's first name if applicable.
last_name_2
string		 No Co-purchaser's last name if applicable.
address_1
string		 Yes Purchaser's street address.
address_2
string		 No Apt, Unit, etc.
city
string		 Yes Purchaser's city.
state
string		 Yes Purchaser's 2 letter state code, all caps.
zip
string		 Yes Purchaser's 5 digit zip code.
phone
string		 Yes Purchaser's 10 digit phone number, digits only.
email
string		 No Purchaser's email address.

Sample JSON Response

{
  "api_name": "Cuvrd Term Contract Vendor API",
  "version": "1.5.0",
  "step": 2,
  "success": 1,
  "error_code": 0,
  "response_message": "Request successful.",
  "request_date_time": "2023-01-30 15:40:52",
  "vin": "2FMDK4JC0EBA13750",
  "vehicle_year": "2014",
  "vehicle_make": "FORD",
  "vehicle_model": "EDGE",
  "vehicle_series": "EDGE SEL AWD",
  "total_customer_cost": 4200,
  "tax_collected": 128,
  "total_vendor_cost": 1464,
  "vendor_markup": 2736,
  "contract_purchase_date": "2022-02-01",
  "contract_id": "3710152173",
  "program_name": "Secure Advantage",
  "plan_level": "Diamond",
  "plan_coverage_type": "VSC",
  "new_or_used": "New",
  "wait_days": 30,
  "wait_miles": 1000,
  "deductible": 100,
  "program_term_months": 72,
  "program_miles": 75000,
  "net_covered_miles": 32999,
  "expiration_miles": 76000,
  "add_on_miles": 0,
  "options": [
    {
      "code": "elr",
      "description": "Enhanced Labor"
    },
    {
      "code": "av",
      "description": "Technology Group Coverage"
    },
    {
      "code": "emi",
      "description": "Emissions Coverage"
    },
    {
      "code": "lft",
      "description": "Lift Kit - Dealer Installed Only"
    },
    {
      "code": "com",
      "description": "Light Commercial Vehicle"
    },
    {
      "code": "snp",
      "description": "Snow Plow"
    }
  ],
  "purchaser": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "address_1": "111 N. Any Street",
      "address_2": "Unit A",
      "city": "S. Anytown",
      "state": "SC",
      "zip": "02184",
      "phone": "8885551212",
      "email": "jd@example.com"
    }
  ],
  "leinholder_name": "Federal Vehicle Loans Inc.",
  "document_name": "37111222333",
  "document_extension": ".pdf",
  "document_id": "111111aaaaaabbbbbbcccccc22222233",
  "document_url": "https://restapi.cuvrd.com/term_vsc/docs/pdf/?doc_name=37111222333&doc_id=111111aaaaaabbbbbbcccccc22222233"
}

Purchase Request Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Term Contract Vendor API - Purchase request response",
  "description": "Term contract purchase request response schema.",
  "required": [
    "api_name",
    "version",
    "step",
    "success",
    "error_code",
    "response_message",
    "request_date_time"
  ],
  "properties": {
    "api_name": {
      "type": "string",
      "description": "Name of this API.",
      "example": "Cuvrd Term Contract Vendor API"
    },
    "version": {
      "type": "string",
      "description": "Semantic version of this API.",
      "example": "1.0.0"
    },
    "step": {
      "type": "integer",
      "description": "The response step in this API's sequence.",
      "example": 1
    },
    "success": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Flag to indicate a successful request and response. Success = 1, Fail = 0",
      "example": 1
    },
    "error_code": {
      "type": "integer",
      "description": "0 if successful, integer > 0 if failure. See appendix for a list of error codes.",
      "example": 1
    },
    "response_message": {
      "type": "string",
      "description": "Success or full text response of the error_code field.",
      "example": "Request successful."
    },
    "request_date_time": {
      "type": "string",
      "description": "date-time this request was processed",
      "example": "2021-01-01 12:34:26"
    },
    "vin": {
      "type": "string",
      "minLength": 17,
      "maxLength": 17,
      "description": "17 character vehicle identification number sent in request",
      "example": "3R63R3GL3JG236800"
    },
    "vehicle_year": {
      "type": "string",
      "description": "Vehicle year decoded from VIN",
      "example": "2018"
    },
    "vehicle_make": {
      "type": "string",
      "description": "Vehicle make decoded from VIN",
      "example": "TOYOTA"
    },
    "vehicle_model": {
      "type": "string",
      "description": "Vehicle model decoded from VIN",
      "example": "CAMRY"
    },
    "vehicle_series": {
      "type": "string",
      "description": "Extended vehicle model information decoded from VIN",
      "example": "CAMRY XLE"
    },
    "total_customer_cost": {
      "type": "number",
      "description": "Pre-tax retail cost of this service contract to the customer.",
      "example": 2652
    },
    "tax_collected": {
      "type": "number",
      "description": "Sales tax collected for this VSC.",
      "example": 128
    },
    "total_vendor_cost": {
      "type": "number",
      "description": "Wholesale cost of this service contract to the vendor. This is the amount that must be remitted to the administrator.",
      "example": 652
    },
    "vendor_markup": {
      "type": "number",
      "description": "The amount of profit retained by the vendor. Comprised of total_customer_cost minus total_vendor_cost.",
      "example": 2000
    },
    "contract_purchase_date": {
      "type": "string",
      "format": "date",
      "description": "The official purchase date of this service contract, ANSI date formatted string",
      "example": "2022-01-01"
    },
    "contract_id": {
      "type": "string",
      "description": "The contract number/id assigned to this service contract.",
      "example": "361014765"
    },
    "program_name": {
      "type": "string",
      "description": "The trade name for this service contract",
      "example": "Horizon"
    },
    "plan_level": {
      "type": "string",
      "description": "Description of the coverage level of this service contract (Platinum, Gold, Silver, etc.)",
      "example": "GOLD"
    },
    "new_or_used": {
      "type": "string",
      "description": "Denotes new car coverage (expires when odometer reaches program miles) or used (expires when program miles are travelled from date of purchase)."
    },
    "wait_days": {
      "type": "integer",
      "description": "Number of days after the service contract has been purchased before going into service--typically 30 days",
      "example": 30
    },
    "wait_miles": {
      "type": "integer",
      "description": "Number of miles driven after the service contract has been purchased before going into service--typically 1000 miles.",
      "example": 1000
    },
    "deductible": {
      "type": "number",
      "description": "Deductible amount per repair the purchaser is responsible for paying out of pocket.",
      "example": 100
    },
    "program_term_months": {
      "type": "integer",
      "description": "Length in months of this plan",
      "example": 48
    },
    "program_miles": {
      "type": "integer",
      "description": "Length in miles of this service contract",
      "example": 48000
    },
    "net_covered_miles": {
      "type": "integer",
      "description": "The net number of miles that this service contract will be in effect",
      "example": 48000
    },
    "expiration_miles": {
      "type": "integer",
      "description": "The contract coverage will end when the vehicle odometer reaches this value",
      "example": 97465
    },
    "add_on_miles": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "0 = coverage ends when *vehicle odometer* reaches program_miles value, 1 = coverage ends when *traveled miles* equals program_miles",
      "example": 1
    },
    "options": {
      "type": "array",
      "description": "Array of additional coverages that are either included in this plan or were purchased as an option.",
      "additionalItems": true,
      "items": {
        "type": "object",
        "description": "Additionally purchased or included coverages.",
        "required": [
          "code",
          "description"
        ],
        "properties": {
          "code": {
            "type": "string",
            "enum": [
              "elr",
              "av",
              "emi",
              "com",
              "lft",
              "snp"
            ],
            "description": "The short code for this specific option. See appendix for optional coverage types.",
            "example": "elr"
          },
          "description": {
            "type": "string",
            "description": "Clear text description of this coverage",
            "example": "Enhanced Labor"
          }
        },
        "additionalProperties": true
      }
    },
    "purchaser": {
      "type": "object",
      "properties": {
        "first_name": {
          "type": "string",
          "maxLength": 20,
          "description": "Purchaser's first name"
        },
        "last_name": {
          "type": "string",
          "maxLength": 20,
          "description": "Purchaser's last name"
        },
        "first_name_2": {
          "type": "string",
          "maxLength": 20,
          "description": "OPTIONAL - Co-purchaser's first name if applicable"
        },
        "last_name_2": {
          "type": "string",
          "maxLength": 20,
          "description": "OPTIONAL - Co-purchaser's last name if applicable"
        },
        "address_1": {
          "type": "string",
          "maxLength": 30,
          "description": "Purchaser's street address"
        },
        "address_2": {
          "type": "string",
          "maxLength": 30,
          "description": "OPTIONAL - Apt, Unit, etc."
        },
        "city": {
          "type": "string",
          "maxLength": 20,
          "description": "Purchaser's city"
        },
        "state": {
          "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": "Purchaser's 2 letter state code, all caps."
        },
        "zip": {
          "type": "string",
          "minLength": 5,
          "maxLength": 5,
          "description": "Purchaser's 5 digit zip code",
          "example": "02184"
        },
        "phone": {
          "type": "string",
          "minLength": 10,
          "maxLength": 10,
          "description": "Purchaser's 10 digit phone number - digits only",
          "example": "3125551212"
        },
        "email": {
          "type": "string",
          "maxLength": 30,
          "description": "Purchaser's email address"
        }
      },
      "required": [
        "first_name",
        "last_name",
        "address_1",
        "city",
        "state",
        "zip",
        "phone"
      ]
    },
    "leinholder_id": {
      "type": "string",
      "description": "leinholder_id of the leinholder chosen from the results response OR leinholder_ext for vendor-transmitted leinholders."
    },
    "leinholder_name": {
      "type": "string",
      "description": "Clear text name of the leinholder for display purposes",
      "example": "American National Bank"
    },
    "document_name": {
      "type": "string",
      "description": "Name of the service contract document without the file extension."
    },
    "document_extension": {
      "type": "string",
      "description": "File extension of the service contract document (document_name + document_extension = full document name)."
    },
    "document_id": {
      "type": "string",
      "description": "Document UID needed to obtain this document."
    },
    "document_url": {
      "type": "string",
      "description": "URL of the purchaser's service contract in PDF format."
    }
  },
  "additionalProperties": true
}

Reporting Request

Reporting API Endpoint:

POST /term_vsc/v1/booked_contracts/

Header:

Content-Type: application/json

Body Parameters

A note about the reporting request:

You can simply send your vendor_id and api_key with no other keys to retrieve the last 90 days of booked contracts. record_count, days_ago_start, days_ago_end are not necessary in most cases unless you are looking for a range of contracts booked more than 90 days ago.

Key/Type Required Description
vendor_id
integer		 Yes The vendor ID provided by Cuvrd.
api_key
string		 Yes Secret alphanumeric string provided by Cuvrd.
record_count
integer		 No Number of records to return. 0 = all records from the past 90 days.
days_ago_start
integer		 No Return records in the range starting X days ago. Default is 90 days ago.
days_ago_end
integer		 No Return records in the range ending X days ago. Default is 0 which = today.

cURL example

curl --location --request POST 'https://restapi.cuvrd.com/term_vsc/v1/booked_contracts/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "vendor_id": 22112,
    "api_key": "396e7b13501d5286b166695081cfd2d8d40019aa"
}'

Sample JSON Request

{
  "vendor_id": 22112,
  "api_key": "396e7b13501d5286b166695081cfd2d8d40019aa"
}

Reporting Request Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "title": "Cuvrd Term Contract Vendor API - Booked Contract Report request",
  "description": "Booked contract report request schema. Default report will return the last 90 days worth of booked contracts if the last three keys are not sent OR the last three keys are sent with the value [0]",
  "properties": {
    "vendor_id": {
      "type": "integer"
      "minimum": 20000,
      "maximum": 99999,
      "description": "The vendor ID provided by Cuvrd.",
      "example": 22112    },
    "api_key": {
      "type": "string"
      "minLength": 40,
      "maxLength": 40,
      "description": "40 character alphanumeric string provide by Cuvrd.",
      "example": "396e7b13501d5286b166695081cfd2d8d40019aa"
    },
    "record_count": {
      "type": "integer"
      "minimum": 0,
      "description": "Number of records to return. 0 = all records from the past 90 days."
    },
    "days_ago_start": {
      "type": "integer"
      "minimum": 0,
      "description": "Return records in the range starting X days ago. Default is 90 days ago."
    },
    "days_ago_end": {
      "type": "integer"
      "minimum": 0,
      "description": "Return records in the range ending X days ago. Default is 0 which = today."
    }
  },
  "required": [
    "vendor_id",
    "api_key"
  ]
}

Reporting Response

Response Parameters

Key/Type Required Description
contract_id
integer		 Yes The contract number/id assigned to this service contract.
app_id
string		 Yes Vendor's internal ID for this purchaser; passed to Cuvrd during the purchase step. This value is useful to match your records with the results of this report.
program_name
string		 Yes The trade name for this service contract.
plan_level
string		 Yes Description of the coverage level of this service contract (Platinum, Gold, Silver, etc.).
plan_coverage_type
string		 Yes Type of coverage for this contract (VSC, GAP, PPM, etc.).
new_or_used
string		 Yes Denotes new car coverage (expires when odometer reaches program miles) or used (expires when program miles are travelled from date of purchase).
deductible
number		 Yes Deductible amount per repair the purchaser is responsible for paying out of pocket.
program_term_months
integer		 Yes Length in months of this plan.
program_miles
integer		 Yes Length in miles of this service contract.
net_covered_miles
integer		 Yes The net number of miles that this service contract will be in effect.
expiration_miles
integer		 Yes The contract coverage will end when the vehicle odometer reaches this value.
year
string		 Yes Model year of the purchaser's covered vehicle.
make
string		 Yes Make of the purchaser's covered vehicle.
model
string		 Yes Model of the purchaser's covered vehicle.
series
string		 Yes Extended vehicle model information of the purchaser's covered vehicle.
total_vendor_cost
number		 Yes Wholesale cost of this service contract to the vendor. This is the amount that must be remitted to the administrator.
vendor_markup
number		 Yes The amount of profit retained by the vendor. Comprised of total_customer_cost minus total_vendor_cost.
total_customer_cost
number		 Yes Pre-tax retail price for this VSC. This is the total amount the customer paid for this VSC
tax_collected
number		 Yes New Sales tax collected for this VSC.
contract_purchase_date
string		 Yes The official purchase date of this service contract, ANSI date formatted string.
vin
string		 Yes 17 character vehicle identification number sent in request.
mileage
integer		 Yes Vehicle mileage at time of purchase.
leinholder_id
string		 Yes leinholder_id of the leinholder if chosen from the results response.
leinholder_ext_code
string		 Yes leinholder_ext code provided by the vendor at time of purchase.
leinholder_name
string		 Yes Clear text name of the leinholder for display purposes.
first_name
string		 Yes Purchaser's first name.
last_name
string		 Yes Purchaser's last name.
city
string		 Yes Purchaser's city.
state
string		 Yes Purchaser's 2 letter state code, all caps.
zip
string		 Yes Purchaser's 5 digit zip code.
phone
string		 Yes Purchaser's 10 digit phone number - digits only.
email
string		 Yes Purchaser's email address.
cc_invoice_id
string		 Yes ID number of the credit card invoice sent to the customer (if applicable).
cc_invoice_status
string		 Yes Current status of the credit card invoice sent to the customer(if applicable).
contract_doc_url
string		 Yes URL of the purchaser's service contract in PDF format.
is_paid
string		 Yes Flag to note if Administrator has been paid for this VSC. 0 = no, 1 = yes.
created_on
string		 Yes Date/Time this record was first created.
modified_on
string		 Yes Date/Time this record was last updated.

Sample JSON Response

[
  {
    "contract_id": 541015110,
    "app_id": "MYAPP0001",
    "program_name": "Eclipse",
    "plan_level": "Gold",
    "plan_coverage_type": "VSC",
    "new_or_used": "New",
    "deductible": 100,
    "program_term_months": 60,
    "program_miles": 100000,
    "net_covered_miles": 33000,
    "expiration_miles": 100000,
    "year": "2019",
    "make": "VOLKSWAGEN",
    "model": "ATLAS",
    "series": "ATLAS SE AWD",
    "total_vendor_cost": 1261,
    "vendor_markup": 750,
    "total_customer_cost": 2011,
    "tax_collected": 128.00
    "contract_purchase_date": "2022-11-02",
    "vin": "1V2UR2CA5KC550057",
    "mileage": 67000,
    "leinholder_id": "0",
    "leinholder_ext_code": "ABC12345",
    "leinholder_name": "Federal Vehicle Loans, Inc.",
    "first_name": "John",
    "last_name": "Doe",
    "city": "Austin",
    "state": "TX",
    "zip": "02184",
    "phone": "8885551212",
    "email": "example@test.com",
    "cc_invoice_id": "7756355555",
    "cc_invoice_status": "",
    "contract_doc_url": "https://restapi.cuvrd.com/term_vsc/docs/pdf/?doc_name=37111222333&doc_id=111111aaaaaabbbbbbcccccc22222233",
    "is_paid": 0,
    "created_on": "2022-01-02 10:18:48",
    "modified_on": "2022-11-23 10:19:04"
  },
  {
    "contract_id": 541015111,
    "app_id": "MYAPP0001",
    "program_name": "Secure Advantage",
    "plan_level": "Platinum",
    "plan_coverage_type": "VSC",
    "new_or_used": "New",
    "deductible": 100,
    "program_term_months": 60,
    "program_miles": 100000,
    "net_covered_miles": 33000,
    "expiration_miles": 100000,
    "year": "2019",
    "make": "VOLKSWAGEN",
    "model": "ATLAS",
    "series": "ATLAS SE AWD",
    "total_vendor_cost": 1261,
    "vendor_markup": 750,
    "total_customer_cost": 2011,
    "tax_collected": 128.00
    "contract_purchase_date": "2022-11-02",
    "vin": "1V2UR2CA5KC550057",
    "mileage": 67000,
    "leinholder_id": "0",
    "leinholder_ext_code": "ABC12345",
    "leinholder_name": "Federal Vehicle Loans, Inc.",
    "first_name": "John",
    "last_name": "Doe",
    "city": "Austin",
    "state": "TX",
    "zip": "02184",
    "phone": "8885551212",
    "email": "example@test.com",
    "cc_invoice_id": "7756355556",
    "cc_invoice_status": "",
    "contract_doc_url": "https://restapi.cuvrd.com/term_vsc/docs/pdf/?doc_name=37111222333&doc_id=111111aaaaaabbbbbbcccccc22222233",
    "is_paid": 0,
    "created_on": "2022-01-02 10:18:48",
    "modified_on": "2022-11-23 10:19:04"
  }
]

Reporting Response Schema

{
  "$schema":"http://json-schema.org/draft-07/schema",
  "title":"Cuvrd Term Contract Vendor API - Booked Contract Report Response",
  "description":"Booked contract report request schema. Report will return an array of booked contract objects.",
  "type":"array",
  "items":[
    {
      "type":"object",
      "properties":{
        "contract_id":{
          "type":"integer",
          "description":"The contract number/id assigned to this service contract.",
          "example":"361014765"
        },
        "app_id":{
          "type":"string",
          "description":"Vendor's internal ID for this purchaser; passed to Cuvrd during the purchase step. This value is useful to match your records with the results of this report.",
          "example":"MYAPP1100022"
        },
        "program_name":{
          "type":"string",
          "description":"The trade name for this service contract",
          "example":"Horizon"
        },
        "plan_level":{
          "type":"string",
          "description":"Description of the coverage level of this service contract (Platinum, Gold, Silver, etc.)",
          "example":"GOLD"
        },
        "plan_coverage_type":{
          "type":"string",
          "description":"Type of coverage for this contract (VSC, GAP, PPM, etc.)",
          "example":"VSC"
        },
        "new_or_used":{
          "type":"string",
          "description":"Denotes new car coverage (expires when odometer reaches program miles) or used (expires when program miles are travelled from date of purchase)."
        },
        "deductible":{
          "type":"number",
          "description":"Deductible amount per repair the purchaser is responsible for paying out of pocket.",
          "example":100
        },
        "program_term_months":{
          "type":"integer",
          "description":"Length in months of this plan",
          "example":48
        },
        "program_miles":{
          "type":"integer",
          "description":"Length in miles of this service contract",
          "example":48000
        },
        "net_covered_miles":{
          "type":"integer",
          "description":"The net number of miles that this service contract will be in effect",
          "example":48000
        },
        "expiration_miles":{
          "type":"integer",
          "description":"The contract coverage will end when the vehicle odometer reaches this value",
          "example":97465
        },
        "year":{
          "type":"string",
          "description":"Model year of the purchaser's covered vehicle.",
          "example":"2018"
        },
        "make":{
          "type":"string",
          "description":"Make of the purchaser's covered vehicle.",
          "example":"TOYOTA"
        },
        "model":{
          "type":"string",
          "description":"Model of the purchaser's covered vehicle.",
          "example":"CAMRY"
        },
        "series":{
          "type":"string",
          "description":"Extended vehicle model information of the purchaser's covered vehicle.",
          "example":"CAMRY XLE"
        },
        "total_vendor_cost":{
          "type":"number",
          "description":"Wholesale cost of this service contract to the vendor. This is the amount that must be remitted to the administrator.",
          "example":652
        },
        "vendor_markup":{
          "type":"number",
          "description":"The amount of profit retained by the vendor. Comprised of total_customer_cost minus total_vendor_cost.",
          "example":2000
        },
        "total_customer_cost":{
          "type":"number",
          "description":"Pre-tax retail cost of this service contract to the customer.",
          "example":2652
        },
        "tax_collected":{
          "type":"number",
          "description":"Sales tax collected for this VSC.",
          "example":128
        },
        "contract_purchase_date":{
          "type":"string",
          "description":"The official purchase date of this service contract, ANSI date formatted string",
          "example":"2022-01-01"
        },
        "vin":{
          "type":"string",
          "minLength":17,
          "maxLength":17,
          "description":"17 character vehicle identification number sent in request",
          "example":"3R63R3GL3JG236800"
        },
        "mileage":{
          "type":"integer",
          "description":"Vehicle mileage at time of purchase",
          "example":42000
        },
        "leinholder_id":{
          "type":"string",
          "description":"leinholder_id of the leinholder if chosen from the results response."
        },
        "leinholder_ext_code":{
          "type":"string",
          "description":"leinholder_ext code provided by the vendor at time of purchase."
        },
        "leinholder_name":{
          "type":"string",
          "description":"Clear text name of the leinholder for display purposes",
          "example":"American National Bank"
        },
        "first_name":{
          "type":"string",
          "maxLength":20,
          "description":"Purchaser's first name"
        },
        "last_name":{
          "type":"string",
          "maxLength":20,
          "description":"Purchaser's last name"
        },
        "city":{
          "type":"string",
          "maxLength":20,
          "description":"Purchaser's city"
        },
        "state":{
          "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,
          "maxLength":2,
          "description":"Purchaser's 2 letter state code, all caps."
        },
        "zip":{
          "type":"string",
          "minLength":5,
          "maxLength":5,
          "description":"Purchaser's 5 digit zip code",
          "example":"02184"
        },
        "phone":{
          "type":"string",
          "minLength":10,
          "maxLength":10,
          "description":"Purchaser's 10 digit phone number - digits only",
          "example":"3125551212"
        },
        "email":{
          "type":"string",
          "maxLength":30,
          "description":"Purchaser's email address"
        },
        "cc_invoice_id":{
          "type":"string",
          "description":"ID number of the credit card invoice sent to the customer (if applicable)."
        },
        "cc_invoice_status":{
          "type":"string",
          "description":"Current status of the credit card invoice sent to the customer(if applicable)."
        },
        "contract_doc_url":{
          "type":"string",
          "description":"URL of the purchaser's service contract in PDF format."
        },
        "is_paid":{
          "type":"integer",
          "description":"Flag to note if Administrator has been paid for this VSC. 0 = no, 1 = yes."
        },
        "created_on":{
          "type":"string",
          "description":"Date/Time this record was first created."
        },
        "modified_on":{
          "type":"string",
          "description":"Date/Time this record was last updated."
        }
      },
      "required":[
        "contract_id",
        "app_id",
        "program_name",
        "plan_level",
        "plan_coverage_type",
        "new_or_used",
        "deductible",
        "program_term_months",
        "program_miles",
        "net_covered_miles",
        "expiration_miles",
        "year",
        "make",
        "model",
        "series",
        "total_vendor_cost",
        "vendor_markup",
        "total_customer_cost",
        "contract_purchase_date",
        "vin",
        "mileage",
        "leinholder_id",
        "leinholder_ext_code",
        "leinholder_name",
        "first_name",
        "last_name",
        "city",
        "state",
        "zip",
        "phone",
        "email",
        "cc_invoice_id",
        "cc_invoice_status",
        "contract_doc_url",
        "is_paid",
        "created_on",
        "modified_on"
      ]
    }
  ]
}

Errors

Response Parameters

A note about the error response:

– The error JSON response schema is the same format as the responses for Step 1 and Step 2, and it only contains the required keys.

Key/Type Required Description
api_name
string		 Yes Name of this API.
version
string		 Yes Semantic version of this API.
step
integer		 Yes The response step in this API's sequence.
success
integer		 Yes Flag to indicate a successful request and response. Success = 1, Fail = 0.
error_code
integer		 Yes 0 if successful, integer > 0 if failure. See appendix for a list of error codes.
response_message
string		 Yes Success or full text response of the error_code field.
request_date_time
string		 Yes Date-time this request was processed.

Error Codes

Error Code Error Message
0 Request successful.
10 Invalid API POST data. JSON invalid OR fields missing.
11 Invalid JSON format. The JSON file passed did not pass JSON validation.
12 Invalid vendor_id format. The vendor_id submitted is either NULL or not of type integer.
13 Invalid api_key format. The api_key submitted is either not type TEXT or does not match the length requirements.
14 Invalid VIN format. The VIN submitted is either not type TEXT or does not match the length requirements.
15 Invalid mileage value. The mileage data submitted is either NULL or not of type integer.
16 Invalid vendor_id and/or api_key mismatch. The API credentials provided are incorrect.
17 No match was found for the provided VIN in our rating table. The vehicle may not qualify for coverage for our plans. Check the VIN for errors and rebsubmit if necessary.
18 No plans were found for this vehicle. Either the mileage or age may be out of range to qualify for a plan.
19 Invalid request_token format. The request_token submitted is either not type TEXT or does not match the length requirements (40).
20 Invalid product_id format. The product_id submitted is either not type TEXT or does not match the length requirements (40).
21 Invalid leinholder value. The leinholder code submitted is either NULL or not of type integer.
22 Invalid vehicle_value data. The vehicle_value submitted is either NULL or not of type integer or decimal.
23 Invalid contract_purchase_price data. The contract_purchase_price submitted is either NULL or not of type integer or decimal, or < 1.
24 Invalid contract_purchase_date data. The contract_purchase_date submitted is either an improperly formatted date, not a valid date value, or more than 90 days old.
25 Invalid state value. The 2 character state code submitted is invalid.
26 Invalid zip_code value. The zip_code code submitted is either NULL or not valid.
27 Invalid phone value. The phone submitted is either NULL or not valid.
28 Value passed for Enhanced Labor option is invalid.
29 Value passed for Technology Group option is invalid.
30 Value passed for Emissions Coverage option is invalid.
31 Value passed for Dealer Installed Lift Kit option is invalid.
32 Value passed for Light Commercial Vehicle option is invalid.
33 Value passed for Snow Plow option is invalid.
34 The price_request_token does not match the VIN provided in the initial pricing request.
35 No plans were found for this vehicle. Incorrect product_id value provided or updated mileage is now outside of plan range.
36 Purchase price is less than vendor cost. Customer purchase price must be equal to or greater than the total vendor cost.
37 State code in purchase request does not match the state code given in the price request.
38 Regulations prevent non-dealer or aftermarket VSC sales in this state.
39 Invalid value passed for start_id, not of type int or less than 0.
40 Invalid value passed for record_count, not of type int or less than 0.

Sample JSON Response

{
  "api_name": "Cuvrd Term Contract Vendor API",
  "version": "1.5.0",
  "step": 1,
  "success": 0,
  "error_code": 25,
  "response_message": "Invalid state value. The 2 character state code submitted is invalid.",
  "request_date_time": "2022-01-01 17:20:51"
 }

Error Response Schema

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {
    "api_name": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "step": {
      "type": "integer"
    },
    "success": {
      "type": "integer"
    },
    "error_code": {
      "type": "integer"
    },
    "response_message": {
      "type": "string"
    },
    "request_date_time": {
      "type": "string"
    }
  },
  "required": [
    "api_name",
    "version",
    "step",
    "success",
    "error_code",
    "response_message",
    "request_date_time"
  ]
}