Integrating with API
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
- 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
Updated 10 days ago