Integration Guides

Search and Hand Off

This is what most partners build. You call one endpoint, get priced plans back, show the ones you want to offer, and send the customer to a Chaiz URL to complete the purchase.

You never receive a card number, so you stay out of PCI scope entirely. Chaiz handles payment, the contract, and the confirmation email.

The flow

There are two variants. They use different endpoints and differ only in whether you pass the customer's details along with the search.

Anonymous handoff Pre-filled handoff
Endpoint POST /api/v2/Partners/PlansSearch (and the /Vin, /MakeModelYear, /LicensePlate variants) POST /api/v2/Partners/PlansSearchWithUserInfo/Vin
Vehicle identifiers VIN, license plate, or make/model/year VIN only
You collect Vehicle, state, mileage Also name, email, and full address
Customer experience Fills in their own details at checkout Enters payment only
Conversion Lower, more form filling Higher, less friction

Start with anonymous. Move to pre-filled when you already hold verified customer details and want the conversion lift.

Step 1: search 

curl -X POST https://chaiz-api-uat.azurewebsites.net/api/v2/Partners/PlansSearch/Vin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchCriteria": {
      "vin": "5XXG14J25MG015777",
      "stateShortName": "NY",
      "mileage": 42000
    },
    "tracking": {
      "queryParams": "utm_source=partner&utm_medium=cps&utm_campaign=your-campaign-name"
    }
  }'

tracking, filters, and responseDetailLevel sit at the root of the request, not inside searchCriteria. This trips people up.

Only searchCriteria is required. Leave partner out; we resolve it from your token, and sending a value that disagrees with your token is rejected.

For filters, the other vehicle identifiers, and the difference between the full and lean response shapes, see Plan Search Reference.

Searches take 2 to 8 seconds because Chaiz is collecting live rates from multiple administrators. Use a timeout of at least 30 seconds, and do not retry a slow request. A retry starts a second independent search and quotes the vehicle twice.

Step 2: read the results

Each entry in results is one plan at one price for one duration. The same underlying plan often appears several times at different durations and mileage tiers, which is expected: it is one product on different terms. To show each plan only once, see deduping variants. 

{
  "response": {
    "searchId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "results": [
      {
        "searchResultPlanId": 12345,
        "planName": "Platinum Coverage",
        "displayProviderName": "CAPS Protection Plan",
        "duration": 36,
        "miles": 36000,
        "totalPrice": 1899.99,
        "downpayment": 199.99,
        "monthlyPrice": 141.67,
        "deductible": 100,
        "planChaizRating": 9.2,
        "planRatingVerdict": "Excellent",
        "resultLabels": ["BEST_VALUE"],
        "maintenanceProgram": {
          "description": "Covers essential repairs to keep your car running smoothly",
          "items": [
            { "label": "3 oil changes", "info": "$40 towards a standard oil change." },
            { "label": "1 battery or light replacement", "info": null }
          ],
          "documentUrl": "https://assets.chaiz.com/files/maintenance-program.pdf"
        },
        "planSummaryUrl": "https://chaiz.com/product-details?searchResultPlanId=12345&fp=1",
        "planCheckoutUrl": "https://chaiz.com/checkout?searchResultPlanId=12345&fp=1"
      }
    ]
  },
  "errorResponse": null
}

Responses are wrapped: response holds the payload, errorResponse holds problems. Check errorResponse first. See Errors & Rate Limits.

Prices already account for the vehicle, the mileage, the state, and any restrictions on your account. Do not recalculate or adjust them. What we return is what the customer pays.

A searchResultPlanId is valid for 30 days. After that the handoff URLs stop working and you need a fresh search. Do not cache handoff URLs beyond that, and do not store them as permanent product links.

Step 3: hand off

Every result carries the URLs you need. Pick one and send the customer there.

URL Send the customer here when
planCheckoutUrl They have already decided. Fastest path to a sale.
planSummaryUrl They want to read the coverage first. Lands on the Chaiz plan page, which has its own path to checkout.
planContractUrl Never, as a purchase path. It is the sample contract document, for display or download alongside a plan.

planContractUrl appears on the full response shape only, not the lean Essential one.

What is in a handoff URL 

https://chaiz.com/checkout?searchResultPlanId=12345&fp=1&utm_source=partner&utm_campaign=your-campaign
                           └──────────┬─────────┘ └─┬─┘ └──────────────┬─────────────────────────────┘
                                      │             │                  │
                    the plan and its exact price    │      your tracking params, merged in
                                                    │
                        which checkout experience your account is configured for

Treat these URLs as opaque. Use them exactly as returned.

Do not build handoff URLs yourself, and do not strip or rewrite their query parameters. The host, the path, and fp all come from your account configuration and vary by account and campaign. A hand-assembled URL will silently lose branding, attribution, or the correct checkout behavior. Appending an extra parameter is fine; changing what is already there is not.

Getting credit for the sale

Attribution is not automatic. Pass your campaign in tracking.queryParams on the search call, and we merge it into the handoff URLs we return: 

"tracking": {
  "queryParams": "utm_source=partner&utm_medium=cps&utm_campaign=your-campaign-name&utm_content=api",
  "referrer": "https://your-site.example/vehicle/quote"
}

Your utm_campaign value is agreed with your account manager at onboarding. It is what ties the resulting order back to you in reporting and, where applicable, to payout.

Query parameters on the search request URL itself are also captured and appended. Use tracking.queryParams or the request query string, not both, or your campaign values will be concatenated and attribution may not match. tracking.queryParams is the supported way.

If you do not know which utm_campaign to send, ask dev-support@chaiz.com before launch rather than guessing. An unattributed sale is difficult to reassign after the fact.

Hand off with details pre-filled

POST /api/v2/Partners/PlansSearchWithUserInfo/Vin takes the same search plus a userDetails block, and returns handoff URLs that carry a signed customer session. The customer arrives at checkout with their details already filled in and only enters payment. 

curl -X POST https://chaiz-api-uat.azurewebsites.net/api/v2/Partners/PlansSearchWithUserInfo/Vin \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchCriteria": {
      "vin": "5XXG14J25MG015777",
      "mileage": 42000
    },
    "userDetails": {
      "firstName": "Jane",
      "lastName": "Roe",
      "email": "customer@example.com",
      "address": "100 Example Street",
      "city": "Brooklyn",
      "state": "NY",
      "zip": "11201",
      "phoneNumber": "5551234567"
    }
  }'

Things to know about this variant:

  • VIN only. searchCriteria here takes vin and mileage. There is no make/model/year or license plate equivalent.
  • State comes from userDetails.state, not from searchCriteria. It still drives pricing.
  • Required in userDetails: firstName, lastName, email, address, city, state, zip. phoneNumber and externalId are optional. Send externalId if you want your own identifier carried through to the order.
  • A customer account is created or matched by email. A new email creates an account; a known one is matched and updated, with existing values kept where you send blanks. This is silent and expected.
  • The returned URLs contain a signed session valid for 30 days. Treat them as credentials: do not log them, do not put them in a shared or forwardable place, and do not expose them to anyone other than that customer.

Only send details for a customer who gave them to you and intends to buy. These URLs authenticate the customer to a checkout carrying their name and address. Anyone holding the link holds that session.

What your account controls

Your code does not branch on any of this. It is applied server-side, and the URLs we return already reflect it.

Setting Effect on what you see
Available providers and plans Which results come back at all
Allowed durations Which duration variants appear
Payment terms Whether monthly, pay-in-full, or both are offered at checkout
Checkout branding Your logo and brand color on the Chaiz checkout
Skip the plan detail page Handoff URLs land the customer directly on checkout
Agent-operated checkout Extra confirmation steps for a human agent buying on a customer's behalf
Pricing adjustments and fees The prices in your results

So if you are seeing only 36-month plans, or only one provider, that is configuration, not a bug in your request. Contact dev-support@chaiz.com to review your setup.

Going live

  • Handle the 2 to 8 second latency in your UI. Show a spinner and set a generous timeout.
  • Never retry a slow search. Retry only on an explicit 5xx or a connection failure.
  • Do not cache results or handoff URLs longer than 30 days, and re-search when mileage changes.
  • Confirm your utm_campaign with dev-support@chaiz.com and verify a real test order is attributed to you in UAT before launch.
  • Handle 429 by backing off on the Retry-After header. See Errors & Rate Limits.
  • Swap the base URL to https://api.chaiz.com and swap in your production key, which is a different key from your UAT one.

Next steps

Previous
Send a Lead
Next
Full API Checkout