The Sensible Weather API allows you to provide Weather Guarantees to your customers. This document will guide you through the necessary steps to integrate with our API, from authorization to creating, accepting, declining, and cancelling guarantees, as well as updating bookings.

Authorization

Your application must authorize using our authorization API to access the Sensible Weather APIs.

Bearer Token

A bearer token auth header is required in requests to our REST APIs. The token contains authentication data for your app and the set of permissions. To receive a token, send a request using your API keys to our authorization API.

The response from the authorization endpoint contains the expires_in field which defines the token's expiration in seconds (default expiration is 24 hours). We recommend storing the token in a cache after retrieving it to reduce the number of requests. You can set the expiration time in the cache to be slightly less than the actual token expiration as a buffer.

The API returns a 401: Unauthorized error when the token expires. A new token is required to complete the API request.

📘
Note: only request a new token when your existing token has expired or is about to expire

Working with Quotes

All of the API requests below assume that your application already has a valid bearer token as outlined in the preceding section.

Creating a Quote

Send a request with all required fields to the Create Guarantee Quote endpoint. See Plain Language Usage for guidance on plain language. The API will return a quote object with information about the quote.

Accepting a Quote

If the customer decides they want to accept a quote, do the following:

Send a request to the Accept Guarantee Quote endpoint with the ID of the quote

Declining a Quote

If the customer decides they want to decline a quote, do the following:

Send a request to the Decline Guarantee Quote endpoint with the ID of the quote

Cancelling a Guarantee

Send a request to the Cancel Guarantee endpoint using an ID of a valid Guarantee

Updating a Booking

If a customer would like to update the dates or location of a stay you must cancel the existing guarantee and offer an updated quote as the price of coverage may have changed.

📘
Note: If the update to the booking does not change the coverage amount, the dates, or the location, you do not need to create a new quote.

Send a request to the Cancel Guarantee endpoint with the ID of the Weather Guarantee you would like to cancel
Refund the charge
Send a request to the Create Guarantee Quote endpoint and return the new quote to the user
1. Your UI should indicate that their previous coverage has been refunded to them
Send a request to the Accept Guarantee Quote endpoint with the ID of the quote and send a new charge request