Our APIs require a sequence of calls to be executed in one of two particular flows. One of the flows must be used per each customer journey, for each line of business the customer is purchasing a policy for.
The two available flows only differ in how payment information is passed to our Issue endpoint, which is when a policy is created. The difference is: in one you can pass credit card information directly within the Issue request. On the second flow, you call a separate Tokenization endpoint to tokenize payment information separate from the Issue call and then include the tokenized payment info in the Issue request. Here are the two sequences:
Normal Flow:
Request Underwriting Questions
Request Quote
2.a. Optional, Request another Quote (repeat as needed)
Request Issue
Alternate Flow:
Request Underwriting Questions
Request Quote
2.a. Optional, Request another Quote (repeat as needed)
Request Payment Info Tokenization
Request Issue
In each case information from the prior request must be used as part of the subsequent request. For example, if underwriting questions are provided in the Underwriting Questions response, the answers to the provided questions must be included as part of the Quote request.
Similarly, details from the Quote response must be included in the Issue request.
If you choose to use tokenization for your payment info, data from both the Quote response and the Tokenization response should be used as part of the Issue request.
The details of how this is done are in section 4 below.
The examples below use Postman as the API execution tool. If you are not familiar with Postman, please visit their site at https://www.getpostman.com. We will provide a Postman collection for your use. You may use the API tool of your choice to execute requests. To consume the APIs, carrier must have an “Access Token” which can be generated using below steps:
1. Select the token endpoint from table below based on environment.
2. Receiving the client_id, client_secret, grant_type and available scopes first for Test environment and subsequently for the production environment from Product Representative at Assurant. New APIs are secured using OAuth 2.0 and JSON Web Token (JWT) as the access token.
3. Once the details are available, you can create an http POST request to get the access token using below steps.
4. Setting Authorization as “Basic Auth” and passing client_Id and client_secret.
5. In the request header selecting the Authorization as Basic and in request body passing the OAuth grant type and scope.
6. A successful call will return Access Token in response body.
7. The Access Token can them be use in subsequent calls to the APIs.
8. Separate disclosures and instructions for using them will be provided to you by your Account Executive, those will need to be displayed, and in some cases, agreed to from your site.
Below screenshots shows the execution of steps above.
In the Authorization tab for a request in Postman, use the client_id in the Username field and client_secret in the password field.
How to select Authorization as Basic
In the Headers tab please ensure a header with the key of “Authorization” is present and that its value is “Basic”.
How to pass grant_type and scope
To get a valid token, oauth requires two key value pairs. Please ensure that your body type is x-www-form-url encoded and that both key/value pairs below are passed in the body. The scope value will be provided to you by Assurant. Once all have been provided, click Send to have the request sent to our identity provider.
The access token received in response body as below
The access token received above is an encoded JWT, it expires in 15 minutes (this can change) and can be used multiple times for API requests until it expires, at which point a new one will be required.