Migrating to the Vertical Insure API

This document describes the steps required to migrate off of Vertical Insure's 'API shim' and onto its fully featured API.

Why migrate off of the API shim?

The biggest reason to migrate off of the API shim, and onto Vertical Insure's API, is because our API includes both a quote API and a purchase/bind API, which solves problems and enables new possibilities, including:

• We will be able to see every quote that was offered, and track which of them ended up being purchased, which allows us to determine the conversion rate

• We can tell you what the premium required for the coverage is, rather than requiring you to calculate it on your side and tell us

• Without a separate quote API, it's not possible for you, the partner, to validate with us that a coverage can be purchased before the customer pays, which leads to a customer support headache when the customer has already paid but was unable to receive coverage

Getting Vertical Insure credentials

Instead of the access token you have been using, you will need a client ID and client secret in order to call our API. Because we migrated you onto the API shim, you already have a 'partner' onboarded in our partner portal. Please log into the Partner Portal and use the API Keys tab to make a test client ID and client secret to use in development.

Presenting the offer:

The biggest change for you to make is to dynamically present our offer. Instead of inlcuding a widget with a hardcoded price, you should send an API request to our quote API with the customer's information to create a quote on our system and get back the premium that the customer needs to pay to get the coverage. The easiest way to do this is to utilize our drop-in component which will automatically send the quote request it is loaded and present the offer, including its price and a brief promotional description of the product, in a widget on your page. The documentation linked contains tons of information on how to use the drop-in component.

Plan IDs vs products

With the original USSCI integration, and with the shim, there was a 'plan ID' which we asked you to provide in the bind API URL, which acted as a credential of sorts and also decided which product you were purchasing. On our API, there is no such 'plan ID'. All you have to do is specify in the drop-in component, or with your API call, which product you are interested in.

1. For SportsFee, the equivalent product code in our system is registration-cancellation

2. For CEC / Event Cancellation, the equivalent product code in our system is team-registration.

How to purchase

As described in the drop-in component documentation, if a customer indicates that they want to purchase coverage, a Javascript event will be fired which will indicate the quote ID that the customer wants to purchase. From there, you can call the purchase registration-cancellation or purchase team-registration endpoint to purchase the coverage.

Note that, unlike the quote request, the purchase request requires both your client ID and client secret. The client secret must not be exposed to customers, so it is not safe to conduct the purchase client-side: instead, you should have server-side code perform the purchase request.

If you are collecting payment, and then having Vertical Insure send you an invoice for premium collected at the end of the month, then for the payment_method.token in the purchase API's request body, you should use a value like invoice:_____, where the string on the right side of the colon (:) is an identifier which you will be able to use to correlate items on our invoice to payments in your system.

If you are collecting payment with Stripe, please see our payment docs for details on getting set up with a Stripe Connect account.