Quickstart

Create your API key, get a quote with a checkout link, and make a test purchase. End to end in about 10 minutes. Everything on this page runs against UAT, so nothing you do here is a real sale.

UAT base URL: https://uat-api.chaiz.com. Production is https://api.chaiz.com. Keys are issued per environment and do not work across them.

Get a key

Two calls. The first sends a verification code to your inbox, the second exchanges it for your key.

curl -X POST https://uat-api.chaiz.com/api/v2/Partners/Register \
  -H "Content-Type: application/json" \
  -d '{ "contactEmail": "you@example.com", "displayName": "Example Integration", "agreedToTerms": true }'

curl -X POST https://uat-api.chaiz.com/api/v2/Partners/Register/Verify \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "code": "123456" }'

You should see a 201 with your API key. It is shown only once. Store it in a password manager or vault.

Rules for the verification code

Send code as a string of 6 digits, for example "code": "123456". A JSON integer also works, because codes never start with 0.
The code expires 60 minutes after your first Register call. Calling Register again before then re-sends the same code and does not extend the time.
The 5th wrong code cancels the registration. Register again to get a new code.
Registration takes contactEmail, verification takes email. Verification also accepts contactEmail as an alias when email is missing or empty.
Register and Verify answer 200 and 201 with plain JSON objects, and errors as one plain-text sentence, unlike the rest of the API. See Errors & Rate Limits.

A self-registered key gives you 50 requests per hour and 500 per day. Enough to get up and running and develop a feel for the request and response loop. Before you launch, get in touch to set up your branding, the plans you sell, attribution, and higher request limits. Your production key is issued once we have signed off your implementation. See Going Live.

Get your first quote

Every request from here carries Authorization: Bearer <your-key>.

curl -X POST https://uat-api.chaiz.com/api/v2/Partners/PlansSearch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchCriteria": { "vin": "5XXG14J25MG015777", "stateShortName": "NY", "mileage": 42000 } }'

curl -X POST https://uat-api.chaiz.com/api/v2/Partners/PlansSearch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchCriteria": { "licensePlate": "LUC803", "stateShortName": "MS", "mileage": 42000 } }'

A plate is read together with the state it is registered in.

curl -X POST https://uat-api.chaiz.com/api/v2/Partners/PlansSearch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "searchCriteria": { "make": "KIA", "model": "K5", "year": 2021, "stateShortName": "NY", "mileage": 42000 } }'

Make and model must match our catalog. If a customer typed them, resolve them first with GET /api/v2/Partners/Vehicles/Lookup. Make, model, and year are enough to quote. At checkout we ask for the VIN to confirm the final price (engine and trim matter) and to tie the contract to the specific vehicle.

Test vehicle. The VIN 5XXG14J25MG015777 is a 2021 KIA K5, the same car as the make, model, and year example. Use it again at checkout for the test purchase.

A quote takes 2 to 8 seconds. We are collecting live rates from our providers. Set your client timeout to 30 seconds and do not retry a slow request. A retry quotes the same car twice.

Try it in the API client

Read the result

You should see an HTTP 200 with response.results holding one entry per plan and duration.

Trimmed to the fields that matter on this page:

{
  "response": {
    "searchId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "results": [
      {
        "searchResultPlanId": 12345,
        "planName": "Platinum Coverage",
        "displayProviderName": "CAPS Protection Plan",
        "duration": 36,
        "totalPrice": 3168,
        "downpayment": 88,
        "monthlyPrice": 88,
        "deductible": 100,
        "planChaizRating": 9.2,
        "planSummaryUrl": "https://uat-app.chaiz.com/product-details?searchResultPlanId=12345",
        "planCheckoutUrl": "https://uat-app.chaiz.com/checkout?searchResultPlanId=12345"
      }
    ]
  },
  "errorResponse": null
}

Field	What it is
`searchResultPlanId`	This plan at this exact price. Embedded in the URLs below. Search again when it is older than 30 days.
`monthlyPrice`	Plans of 36 months or less can be paid monthly. Longer plans are paid in full and return `0` here, so show `totalPrice` for those.
`planCheckoutUrl`	Where your customer buys. Payment, contract, and confirmation email are ours from here.
`planSummaryUrl`	The same plan with its coverage detail first. Use it if you are not building the detail view yourself.
`searchId`	Identifies this search. You do not need it for the handoff.

Every response is wrapped the same way: response holds the payload, errorResponse holds problems, only one of them is set. Prices are final and already reflect the vehicle, mileage, state, and your account. Show monthlyPrice, totalPrice, and deductible as returned. Anything you compute yourself will differ from what the customer sees at checkout.

An empty results array is a valid answer: no provider quoted this vehicle in this state at this mileage. See Restrictions and limitations.

Purchase a plan

Open a planCheckoutUrl in your browser. You land on a Chaiz checkout with the plan and price selected. The checkout asks for the customer's details, and for the VIN if you searched by make, model, and year.

The state and vehicle you enter at checkout must match the search. Otherwise the quote and price no longer apply.

Step	What to enter
Contact	The email you want the confirmation sent to, and a 10-digit US phone number
Vehicle	Confirm the vehicle and the current odometer. After a make, model, and year search, enter the VIN `5XXG14J25MG015777` here. The checkout then confirms the plan and price for that exact vehicle, which can take up to 30 seconds
Payment	Card `4111 1111 1111 1111`, any future expiry, any CVC, and a real US address whose ZIP is in the state from your search. Answer the usage question and confirm the vehicle has no pre-existing conditions

After you press Pay, you land on the confirmation page and receive the confirmation email. Nothing you buy on UAT is a real sale, and no money moves.

Congratulations, you sold a VSC 🎉

That was Search and Hand Off, the integration most partners run.

Before the real thing

This page skipped five things to stay short. You need all of them for a real integration:

Make the example real. Spinner, 30-second timeout, a plan detail view (or planSummaryUrl), no retries on slow responses. See Search and Hand Off and the UI Requirements.
Result freshness. Search again after 30 days, and when the mileage changes. See Plan Search Reference.
Errors. Codes are stable, messages are not. See Errors & Rate Limits.
Sign-off and the non-technical bits. Catalog, payment terms, rate limits, W-9, and our review of your implementation before production is switched on. See Going Live.
Make it count. Pass your campaign in tracking.queryParams on every search, so the sale is credited to you. A postback is optional: without one you still get the Mixpanel dashboard and the monthly report. See Postback and attribution.

Choose Your Integration Two ways to integrate, and how to pick yours

Introduction

Authentication