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.

sequenceDiagram
    autonumber
    participant You as Your backend
    participant API as Chaiz API
    participant Cust as Your customer
    participant CO as Chaiz

    alt Anonymous handoff
        You->>API: POST /Partners/PlansSearch
        API-->>You: plans with handoff URLs
    else Pre-filled handoff
        You->>API: POST /PlansSearchWithUserInfo/Vin plus userDetails
        Note right of API: creates or matches the customer account
        API-->>You: plans with URLs carrying a signed session
    end

    Note over API: 2 to 8 seconds either way
    You->>Cust: render the plans you choose to offer
    Cust->>CO: clicks a plan and opens the handoff URL
    Note over CO: anonymous enters details, pre-filled enters payment only
    CO-->>Cust: pays and receives the contract

	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://uat-api.chaiz.com/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, responseDetailLevel, and planVariant 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": 3168,
        "downpayment": 88,
        "monthlyPrice": 88,
        "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://uat-app.chaiz.com/product-details?searchResultPlanId=12345",
        "planCheckoutUrl": "https://uat-app.chaiz.com/checkout?searchResultPlanId=12345"
      }
    ]
  },
  "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.

Your results page has to show certain things before the customer is handed to us, and we review it before production is switched on. See UI Requirements.

A result is a quote for the moment you searched. Search again when it is older than 30 days or the mileage changes, and do not store handoff URLs as permanent product links.

Step 3: hand off

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

flowchart LR
    R["a result"]
    R ==> S["planSummaryUrl"]
    R ==> C["planCheckoutUrl"]
    R ==> K["planContractUrl"]

    S ==> SP["Chaiz plan page"]
    C ==> CP["Chaiz checkout"]
    K ==> KP["Sample contract"]

    SP ==> CP
    CP ==> DONE["Contract issued"]

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://uat-app.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

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 merged in. When the same parameter appears in both places, the one on the request URL wins. Use tracking.queryParams only; it is the supported way, and it keeps you from overriding your campaign by accident.

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.

How a sale is credited, and how to get notified about it on your own endpoint, is on Postback and attribution.

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://uat-api.chaiz.com/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:

Enabled per account. Until Chaiz enables it for your account, this endpoint answers 400 with UserInfoPrefillNotAllowed, however valid the request is. Email dev-support@chaiz.com to have it turned on before you build against it.
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.

Before you go 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.
Search again when a result is older than 30 days or the mileage changes.
Put your campaign in tracking.queryParams on every search.
Handle 429 by backing off on the Retry-After header. See Errors & Rate Limits.

The full checklist, our sign-off, and the switch to production are on Going Live.

Next steps

Plan Search Reference for filters, vehicle identification, response shapes, and how to make searches faster.
UI Requirements for what your results page must show.
Postback and attribution for how sales are credited to you.
Errors & Rate Limits for validation codes and retry behavior.

Send a Lead

Postback & Attribution