Create Offer

Sending a Quote Request

The Create Offer endpoint generates personalized product offerings based on partner business context and customer information. This endpoint uses a schema-driven approach to validate requests and returns one or more products with detailed pricing, policy information, and content for display to customers.

For the full request/response schema, query parameters, and field definitions, see the Create Offer API Specification.

What You Get in the Response

The response from the Create Offer endpoint includes:

• Offer ID - Unique identifier (UUID) for the offer that can be used to confirm the purchase or opt out.
• Session ID - Unique session identifier associated with this offer.
• Offer Config ID - The Offer configuration used to generate this Offer. Can be used in subsequent requests to exclude previously shown offers.
• Currency - The currency code for all pricing.
• Products - List of available products with their configurations. For each product:

  • Quote ID - Used for booking confirmation via the Confirm Offer endpoint
  • Product Type (e.g., xcover-product)
  • Finance Information - Price breakdown including total, tax, surcharge, and commission (each with formatted display values)
  • Policy Dates (start and end dates)
  • Policy Disclosure Statement (PDS) URL
  • Attached Files (documents related to the product)
  • Extra Fields and Experiment data (when requested)
  • Benefits from the pricing engine
• Product Rules - Selection rules controlling how products behave in the UI (visibility, required/optional, interactions between products). Only present when rules are configured for the offer.
• Content - Localized display content including:

  • Offer-level: title, description, terms URL
  • Per-product: title, description, benefits, inclusions, exclusions, extras, disclaimers
• Metadata - Additional response metadata such as experiment data. Only present when applicable.
• Errors - Empty on success.

Making a Create Offers Request

The request structure is defined by your partner's Offer Schema, which validates all incoming data using JSON Schema Draft 7. Every request typically includes:

• schema - Schema identifier for the Offer type. If omitted, the default schema for the partner will be used. If the partner does not have a default schema, omitting this field will return a validation error.
• customer - Customer information (language, currency, country, and optional fields like email, IP address, region, postcode)
• context - Business context data required for offer selection and pricing (product-specific fields defined by your schema)
• partner (optional) - Partner-specific information such as subsidiary, transaction ID, customer ID, and metadata (including an optional metadata.session_id).

For the complete field definitions, required vs. optional fields, and query parameters, see the Create Offer API Specification.

Response Status Codes

Status	Description
200 OK	Offer successfully created with available products
400 Bad Request	Malformed or unparseable request body
401 Unauthorized	Missing or invalid API key
403 Forbidden	Access denied
404 Not Found	Partner not found, no offers exist, no offers match the request context, or no offers pass access control
422 Unprocessable Entity	Request validation failed, all quotes failed to generate, or expression evaluation errors
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Unexpected server error

Error Responses

Create Offer supports the opt-in X-API-Error-Version: v2 header, which returns every error response from this endpoint in one consistent shape. We recommend all new integrations send it.

On a 422 where no quote could be generated, for example, the body carries the code offer_quote_generation_failed and one entry per failed product:

{
  "type": "validation_error",
  "message": "Offer could not be created due to quote generation errors",
  "code": "offer_quote_generation_failed",
  "error_id": "b9c1f0d2-3a4e-4c6b-9f21-7d8e5a0b1c34",
  "errors": [
    {
      "product_config_id": "8f2b41c9-6d7e-4a15-b3c8-1e9f0a2d5b76",
      "quote_id": "3c7d9e21-5b48-4f0a-8d16-2a9c4e7b0f53",
      "code": "offer_quote_pricing_error",
      "details": ["No rate available for the supplied parameters"]
    }
  ],
  "metadata": {
    "selected_offer_id": "5d8a2f61-9c04-4e73-b1a8-3f6e7c0d9b42"
  }
}

The header applies to all of the non-2xx statuses in the table above. See Error Versioning for the full field reference and error code list.

Important Notes

• The id field in each product is the quote ID that must be used when confirming the offer via the Confirm Offer endpoint.
• Performance Tip: For optimal performance and dynamic pricing, always request fresh offers rather than caching offer responses. Server-side configuration is cached for 5 minutes, so very recent config changes may not be reflected immediately.
• Schema Validation: All requests are validated against your partner's Offer Schema. Contact your integration team to understand your specific schema requirements.
• Exclude Offers: Use the exclude_offer_ids query parameter to request a different offer later in a customer journey by excluding a previously shown offer using the offer_config_id returned in the response.

Next Steps

After receiving an Offer response:

1. Display the product information and pricing to your customer
2. Present the content (benefits, inclusions, exclusions, disclaimers)
3. When the customer decides to purchase, use the Confirm Offer endpoint with:

   • The offer id from the response
   • The quote id (from each product) of the selected product(s)
   • Policyholder details (first name, last name, country)
4. If the customer declines, use the Opt-Out endpoint with the offer id for conversion tracking