Insurance

Integrating bundled insurance offers

This feature allows you to offer travelers insurance bundled to car rental rates. The bundled offer can then be displayed as a rate type on the search results page.

Important

Bundled Insurance is currently supported exclusively for the Germany (DE) point of sale.

Insurance coverage

Each car result in the Availability response may include an insurance_coverage object. All insurance information for the car, whether included with the rental at no extra cost or available as a supplemental purchase, is returned under this object. See below for the fields it contains.

Field	Description
`included`	A map of included insurance products from the vendor. Each product contains the same fields as a supplemental product.
`supplemental`	An array of optional purchasable insurance products available for this vehicle.

Included

Collision Damage Waiver (CDW)

The included.collision_damage_waiver object contains the following fields:

Field	Description	Example
`description`	Short name of the coverage.	Collision Damage Waiver
`deductible`	The amount the traveler is responsible for in the event of a covered incident, before coverage applies.
`trip_rate`	A cost that is already rolled into the offer total for informational purposes.

Supplemental

Optional insurance products in the supplemental array have the following fields:

Field	Description	Example
`provider`	Name of the insurance provider.	Car Insurance Vendor
`description`	Short name of the coverage.	Full Protection
`benefits.refundable_deductible`	If present, describes the portion of the deductible that may be refunded in the event of a claim (currency, amount, percent).
`benefits.additional_protection`	An array of additional protections included with the insurance coverage.	Windshield
`trip_rate`	Total price of the insurance for the entire reservation (not per day).
`cancel_penalties`	Cancellation penalties specific to the insurance product. Check these in addition to the car's own `cancel_penalties`.
`links.details`	URL to bundled car and insurance product details page.

Insurance bundle

Availability

To surface insurance-bundled offers, you will use the following query parameters:

Field	Description
`include=insurance_bundle`	Returns `insurance_coverage` in results. Without this, bundled insurance offers will be omitted from the Availability response.
`filter=insurance_bundle`	Restricts results to only cars that have insurance bundling available. Combine with `include=insurance_bundle` to show only bundled results.

Note:

The cost of bundled insurance is not factored into the rate.pricing object in the Availability response, since the API does not yet know if insurance (or which coverage plan) will be bundled with the car offer at the time of booking.
The car's rate.pricing.totals.insurance in the Details response will reflect the total cost of the bundled insurance on the product details page since the API knows the intent at that point is to create a bundle.
Two insurance products are currently offered: full protection and extra cover. Depending on the car rental rate and included coverage, the appropriate insurance product will be offered.

Availability response example

[
  {
    ...
    "insurance_coverage": {
      "included": {
        "collision_damage_waiver": {
          "description": "Collision Damage Waiver",
          "deductible": {
            "billable_currency": {
              "value": "1500.00",
              "currency": "USD"
            },
            "request_currency": {
              "value": "1500.00",
              "currency": "USD"
            }
          }
        }
      },
      "supplemental": [
        {
          "provider": "[vendor name]",
          "description": "Full Protection",
          "benefits": {
            "refundable_deductible": {
              "currency": "USD",
              "amount": "1500.00",
              "percent": "100%"
            }
          },
          "trip_rate": {
            "billable_currency": {
              "value": "100.00",
              "currency": "USD"
            },
            "request_currency": {
              "value": "100.00",
              "currency": "USD"
            }
          },
          "cancel_penalties": [
            {
              "end": "2018-02-12T11:59:00",
              "currency": "USD",
              "amount": "100.00"
            }
          ],
          "links": {
            "details": {
              "method": "GET",
              "href": "https://test.ean.com/v2/cars/1234/details?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
            }
          }
        }
      ]
    },
    ...
    "cancel_penalties": [
      {
        "currency": "USD",
        "start": "2018-02-12T11:59:00",
        "end": "2018-02-12T11:59:00",
        "amount": "50.00"
      }
    ],
    "links": {
      "details": {
        "method": "GET",
        "href": "https://test.ean.com/v2/cars/1234/details?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
      }
    }
  }
]

Details

Endpoint: GET /v2/cars/{car_rental_id}/details

The Details link for bundled insurance is provided in the Availability result under links.details in the supplemental InsuranceProduct. Call it to get full pricing, policies, and the booking link.

The insurance_coverage object presented here has the same structure as in Availability. Use this as the authoritative version before check out.

Note: Prices and policy details here take precedence over those in the Availability response.

Supplemental coverage

See below for the fields contained in insurance_coverage.supplemental.

Field	Description	Example
`provider`	Name of the insurance provider.	Car Insurance Vendor
`description`	Short name of the coverage.	Full Protection
`benefits.refundable_deductible`	If present, describes the portion of the deductible that may be refunded in the event of a claim (currency, amount, percent).
`benefits.content`	Array of `{ title, description }` objects for displaying coverage benefit details to the traveler.
`benefits.additional_protection`	An array of additional protections included with the insurance coverage.	Windshield
`disclaimer`	Text the traveler must agree to before adding insurance at check out. Display this and capture acceptance before booking.
`trip_rate`	Total price of the insurance for the entire reservation (not per day).
`cancel_penalties`	Cancellation penalties specific to the insurance product. Check these in addition to the car's own `cancel_penalties`.
`links.terms_and_conditions`	URL to the insurance T&Cs.
`links.product_information`	URL to the insurance product information document (IPID).

Additional fields relevant to insurance

Field	Description
`rate.pricing.totals.insurance`	Total insurance cost for the bundled rate.

Details response example

{
  ...
  "insurance_coverage": {
    "included": {
      "collision_damage_waiver": {
        "description": "Collision Damage Waiver",
        "deductible": {
          "billable_currency": {
            "value": "1500.00",
            "currency": "USD"
          },
          "request_currency": {
            "value": "1500.00",
            "currency": "USD"
          }
        }
      }
    },
    "supplemental": [
      {
        "provider": "[vendor name]",
        "description": "Full Protection",
        "benefits": {
          "refundable_deductible": {
            "currency": "USD",
            "amount": "1500.00",
            "percent": "100%"
          },
          "content": [
            {
              "title": "Zero excess if the vehicle is damaged or stolen",
              "description": "Full Protection covers the full excess amount so you won’t have to pay if something goes wrong."
            },
            {
              "title": "Damages commonly excluded by rental companies",
              "description": "Includes windows, windscreens, tyres, wheels, mirrors/glass, roof, underbody, hitting an animal and more"
            },
            {
              "title": "Roadside assistance and repair costs",
              "description": "Includes towing, key loss & replacement and vehicle lockout"
            },
            {
              "title": "Free cancellation at anytime before pick-up"
            }
          ]
        },
        "disclaimer": "By adding protection you confirm you have read and agree to the Policy Terms and Insurance Product Information Document. By selecting this insurance you confirm you are a resident of Germany, and you are over 18 years old.",
        "trip_rate": {
          "billable_currency": {
            "value": "100.00",
            "currency": "USD"
          },
          "request_currency": {
            "value": "100.00",
            "currency": "USD"
          }
        },
        "cancel_penalties": [
          {
            "end": "2018-02-12T11:59:00",
            "currency": "USD",
            "amount": "100.00"
          }
        ],
        "links": {
          "terms_and_conditions": {
            "method": "GET",
            "href": "https://www.rentalcover.com/policy-wording/collinsoneu-fp-ob"
          },
          "product_information": {
            "method": "GET",
            "href": "https://static.xcover.com/media/pds/7fd53012-812d-4316-bb72-95f46534da7e/Expedia_RC-FP-DE.pdf"
          }
        }
      }
    ]
  },
  ...
  "rate": {
    ...
    "pricing": {
      ...
      "totals": {
        ...
        "insurance": {
          "request_currency": {
            "value": "100.00",
            "currency": "USD"
          }
        },
        ...
      }
    }
  },
  ...
  "cancel_penalties": [
    {
      "currency": "USD",
      "start": "2018-02-12T11:59:00",
      "end": "2018-02-12T11:59:00",
      "amount": "50.00"
    }
  ],
  "links": {
    "payment": {
      "method": "POST",
      "href": "https://pay-test.ean.com/v1/payments?token=K~IjZ45n9y8TKnmQeJ2jQKZxJcYDFCOjkqIl6wLmcyVQlZBVUKLZctxg=="
    },
    "book": {
      "method": "POST",
      "href": "https://test.ean.com/v2/itineraries/car?token=MY5S3j36cOcLfLBZjPYQ1abhfc8CqmjmFVzkk7euvWaunE57LLeDgaxm516m"
    }
  }
}

Payment registration

Endpoint: POST /v2/payments?token=<TOKEN>

The Payment Registration link is provided in the Details response under links.payment in the response body. Call it to register a payment method and get a payment_token for booking.

Book

Endpoint: POST /v2/itineraries/car

Use the book link from the Details response. The token in that link carries all session state, including bundled insurance.

See below for additional request body fields relevant to insurance.

Field	Description
`primary_driver.country_of_residence`	2-letter ISO 3166-1 alpha-2 country code of the driver's primary residence. This field is mandatory when the booking includes insurance coverage.
`primary_driver.state_province_code`	2-letter state/province code or 3-letter subdivision code of the driver's primary residence, to be provided in ISO 3166-1 alpha-2 or ISO 3166-1 alpha-3 format. This field is required when booking a car with insurance coverage.

A successful booking returns HTTP 201 with:

itinerary_id - The permanent booking reference.
links.retrieve - Use this link to fetch booking details.

Retrieve

Endpoint: GET /itineraries/{itinerary_id}/car

Use the retrieve link from the Booking response, or look up by affiliate_reference_id via GET /itineraries/car?affiliate_reference_id=.....

There may be a brief delay after booking before the itinerary is available for retrieval. If you receive an error immediately after booking, please wait a few minutes and retry.

The response (RetrieveResponse) includes but is not limited to:

Field	Description	Example
`itinerary_id`	The booking's itinerary ID.
`status`	Current booking status.	`BOOKED`
`confirmation_id`	Vendor confirmation number.
`car_details`	Full `CarDetails` object including `insurance_coverage`, `rate`, `policies`, and `rules_and_restrictions`.
`primary_driver`	Driver details as submitted at booking.
`affiliate_reference_id`	The Affiliate Reference ID, as submitted at booking.
`affiliate_metadata`	Metadata submitted at booking.
`creation_time`	Booking creation timestamp in ISO 8601 format.
`links.cancel`	`DELETE` link to cancel the booking.
`policy_id`	The insurance booking reference	12345C4R1NS

The car_details.insurance_coverage in the Retrieve response reflects the insurance that was booked. Refer to insurance_coverage.supplemental[].cancel_penalties and the car-level cancel_penalties for refund and cancellation terms.

Note: policy_id is generated asynchronously after booking and may not appear immediately on a retrieve call. The policy_id might then appear on a later call.

Retrieve response example

...
      "supplemental": [
        {
          "policy_id": "12345C4R1NS",
          "provider": "Cover Genius",
          "description": "Full Protection",
          "benefits": {
            "additional_protection": [
              "windshield",
              "windows",
              "mirrors",
              "wheels",
              "tires"
            ],
            "refundable_deductible": {
              "currency": "USD",
              "amount": "1500.00",
              "percent": "100%"
            },
            "content": [
              {
                "title": "Zero excess if the vehicle is damaged or stolen",
                "description": "Full Protection covers the full excess amount so you won’t have to pay if something goes wrong."
              },
              {
                "title": "Damages commonly excluded by rental companies",
                "description": "Includes windows, windscreens, tyres, wheels, mirrors/glass, roof, underbody, hitting an animal and more"
              },
              {
                "title": "Roadside assistance and repair costs",
                "description": "Includes towing, key loss & replacement and vehicle lockout"
              },
              {
                "title": "Free cancellation at anytime before pick-up"
              }
            ]
          },
          "disclaimer": "By adding protection you confirm you have read and agree to the Policy Terms and Insurance Product Information Document. By selecting this insurance you confirm you are a resident of Germany, and you are over 18 years old.",
          "trip_rate": {
            "billable_currency": {
              "value": "100.00",
              "currency": "USD"
            },
            "request_currency": {
              "value": "100.00",
              "currency": "USD"
            }
          },
          "cancel_penalties": [
            {
              "end": "2018-02-12T11:59:00",
              "currency": "USD",
              "amount": "100.00"
            }
          ],
          "links": {
            "terms_and_conditions": {
              "method": "GET",
              "href": "https://www.rentalcover.com/policy-wording/collinsoneu-fp-ob"
            },
            "product_information": {
              "method": "GET",
              "href": "https://static.xcover.com/media/pds/7fd53012-812d-4316-bb72-95f46534da7e/Expedia_RC-FP-DE.pdf"
            }
          }
        }
      ]
      ...

Cancel

Endpoint: DELETE /itineraries/{itinerary_id}/car

Use the cancel link from the Retrieve response to cancel the bundled car and insurance booking.

Note: In the bundled insurance booking scenario, the supplemental insurance product cannot be canceled individually. The only option is to cancel the entire bundle, which is subject to the cancel_penalties of the car itself as well as the supplemental insurance. The most restrictive combination of the two arrays of cancel_penalties will be used to determine eligibility for cancellation.

API details

Explore the booking management endpoint definitions on this page, then use the API Explorer or another testing software to get an understanding of how the examples and schema definitions compare to the actual output.

Additional resources

Whether you're looking to try out all the Rapid Car API endpoints or to download its OpenAPI specs, we have what you need.