Server side

This page guides migration from the make booking request to the confirm offer request on the server side.

When migrating from the Quote & Bind to the Offers API, the server-side flow changes from POST booking to POST confirm offer. The core structure stays familiar — you still pass a quotes array and a policyholder — but the endpoint, path parameters, and several request/response fields are different.

The offer_id required by the new endpoint comes from the provider_reference field returned by XCover Elements on the frontend. Make sure your client-side migration is complete before updating the server-side integration.

Endpoint

	Quote & Bind (old)	Offers (new)
Method	POST	POST
Path	/x/partners/{partner_code}/bookings/{quote_package_id}	/x/partners/{partner_code}/offers/{offer_id}/confirm/

Path parameters

Parameter	Quote & Bind (old)	Offers (new)
partner_code	partner_id — your unique Partner Code	Same
Resource ID	quote_package_id — from the quote response	offer_id — from the XCE provider_reference field

Request headers

Authentication headers (X-Api-Key, Date, Authorization) remain unchanged. The x-idempotency-key header is also supported by both endpoints — responses are cached for 48 hours and duplicate requests within that window return 409 with the cached result.

Request body

The request body structure is the same: a quotes array and a policyholder object.

quotes array

The quote object structure is the same between both endpoints:

Field	Type	Description
id	string	Required — quote ID (from the offer response)
insured	array	Optional — insured persons
instalment_plan	string	Optional — selected payment plan identifier
first_instalment_paid	boolean	Optional — whether the first instalment has been collected

policyholder object

No breaking changes. The same rules apply to both endpoints.

Field	Quote & Bind (old)	Offers (new)
first_name	Required	Required
last_name	Required	Required
email	Required*	Required*
country	Required	Required
phone	Optional*	Optional*
birth_date	Optional	Optional
region, city, postcode, address1, address2	Optional	Optional

* Either email or phone must be present. phone alone is accepted only when the partner has phone number verification enabled.

Example request

POST /x/partners/{partner_code}/offers/{offer_id}/confirm/
Content-Type: application/json
X-Api-Key: {your_api_key}
Date: Sun, 09 Nov 2025 04:04:00 GMT
Authorization: SIGNATURE {hmac_signature}

{
  "quotes": [
    {
      "id": "{product_id}",
      "insured": [
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "birth_date": "1990-01-15",
          "email": "[email protected]"
        }
      ]
    }
  ],
  "policyholder": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "phone": "[phone]",
    "country": "US"
  },
  "partner_transaction_id": "your-internal-order-id"
}

Response

The response shape is largely the same. Key fields for reference:

Field	Quote & Bind (old)	Offers (new)
status	CONFIRMED on success	Same
total_price	Present	Present
total_price_formatted	Present	Present
pds_url	Present	Present
coi	Present	Present
account_url	Present	Present
sign_up_url	Present	Present
fnol_link	Present	Present

Validate the total_price in the response against the price shown at the offer stage to confirm the final price matches what the customer saw before confirming.

Error handling

The key difference in error handling is how booking failures are surfaced.

In Quote & Bind, a booking attempt can return 200 with an errors field on individual quotes in the response — a partial success where some quotes failed but the overall request succeeded. You must inspect each quote's errors field to detect failures.

In Confirm Offer, there is no partial success concept. Any failure is returned as an HTTP error status code, so standard HTTP error handling is sufficient.

Please refer to this Confirm Offer Workflow and Confirm Offer API Reference for more detail.