Fully Embedded Experience
Here developers will use our remaining suite of APIs to guide a customer to a bound policy.
Note: Root is continuously improving our endpoints! Expect frequent, non-breaking changes to accept/give additional data or otherwise improve developer and customer experience. Changes will always be communicated in our change log.
Fully Embedded Sequence Diagram
5. Get Available Coverages
← See Getting Started for steps 1-4
This will return all possible coverages available for a given market. From there a partner could build a client user experience to display all possible coverages. The API integration should be aware that available coverages may change as profile information changes. (For example, by regulation in some states we must offer certain coverage modifiers only to certain age groups).
Note: Profile must have a state set prior to using this endpoint
Although all coverages provided are individually valid, that does not mean every combination of coverages are valid together. See Step 7 for providing coverage selections and associated validations
GET: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/coverages/available
6. Get Suggested Coverages
A starting point to get a valid set of coverages. There are a couple of ways these can be used:
- If you are building out a quote customization user experience (using Step 5), the suggested coverages can be used to pre-populate the UX as kind of a starting position to let the customer customize their coverages.
- This will provide a quick valid set of coverages that are readily able to be attached to a quote
GET: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/coverages/suggested
- Utilizing the rules from the Get coverage rules endpoint can help guide coverage customization while avoiding invalid combinations (see Coverage Customization for more details)
GET: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/coverages/rules
7. Provide Customer Coverage Selection
Just like customers provide profile information, they will also need to make coverage selections that fit their needs. Whether that is from our suggested coverages or not. These include providing both policy coverages and vehicle coverages.
PUT: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}
Example of Updating profile with coverage selections
{
"profile": { /* SEE STEP #4 FOR PROFILE EXAMPLES */ },
"coverageSelections": {
"policy": [
{
"symbol": "bi",
"attributes": [
{
"kind": "limits",
"selection": {
"perDay": 100,
"perOccurrence": 300
}
}
]
},
{
"symbol": "pd",
"attributes": [
{
"kind": "limits",
"selection": {
"perOccurrence": 100000
}
}
]
},
{
"symbol": "med_pay",
"attributes": [
{
"kind": "limits",
"selection": {
"perPerson": 1000
}
}
]
},
{
"symbol": "umuim",
"attributes": [
{
"kind": "limits",
"selection": {
"perDay": 250,
"perOccurrence": 500
}
}
]
}
],
"vehicles": [
{
"vin": "JTHBW1GG8E2042488",
"coverages": [
{
"symbol": "coll",
"attributes": [
{
"kind": "deductible",
"selection": {
"deductible": 1000
}
},
{
"kind": "modifier",
"selection": {
"id": "123"
}
}
]
},
{
"symbol": "comp",
"attributes": [
{
"kind": "deductible",
"selection": {
"deductible": 100
}
}
]
},
{
"symbol": "rental",
"attributes": [
{
"kind": "limits",
"selection": {
"perDay": 40,
"perOccurrence": 1200
}
}
]
}
]
}
]
}
}
In the event a combination of coverage selections are not allowed, the response will include "valid": false and a displayable "message" attribute for the user to correct their selections. Example below:
{
"quote": {
"id": "9f3bf07d-ca46-4e67-a123-0231512d9eed",
"status": "collecting_data",
"kind": "none",
"invoicePeriod": null,
"expiresOnOrBefore": null,
"profile": {...},
"coverages": {
"policy": [
{
"attributes": [
{
"kind": {
"value": "limits",
"valid": true,
"message": null,
"requirements": []
},
"selection": {
"value": {
"description": "Limits",
"perDay": null,
"perOccurrence": 50000,
"perPerson": 25000
},
"valid": true,
"message": null,
"requirements": []
},
"description": "This coverage has limits on the amounts that might be paid out in case of a claim",
"name": "Limits"
}
],
"symbol": {
"value": "bi",
"valid": false,
"message": "Uninsured and Underinsured Motorist Bodily Injury selection cannot be higher than selected Bodily Injury coverages",
"requirements": [
{
"fulfilled": false,
"kind": "invalid",
"message": "Uninsured and Underinsured Motorist Bodily Injury selection cannot be higher than selected Bodily Injury coverages"
}
]
},
"description": "Bodily Injury",
"name": "Bodily Injury"
},
...
],
...
}
}
}
All coverage symbols must either have a selection or an explicit declination (and for vehicle-level coverages those must be explicitly selected or declined per vehicle as well)
8. Finalize Quote
Added as a flow requirement on 1/5/23
"Finalizing" a quote allows a partner/customer to signal to Root that there is intent to bind. Providing an invoice period to this endpoint will "lock" the quote in its current state, which behind the scenes enables Root to:
- Pull any additional 3rd party reports
- Determine final underwriting decisions
- Generate all legal documents for a customer to review prior to binding a policy
This endpoint will return a 202 accepted response if the existing quote is in a ready-to-bind state. At this point, you can retrieve your quote one last time to confirm it's of kind: "finalized_quote".
POST: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/finalize
9. Poll Get Quote
Since Root deals with 3rd parties to pull final reports and final underwriting decisions are not instantaneous, polling the GET endpoint will be required to know when the quote has been updated to a kind: "finalized_quote", status: "quoted".
GET: https\://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}
10. Get Legal Documents
All customer must acknowledge and affirm all documents related to the policy they intent to bind.
GET: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/legal_documents
Items to pay attention to here
legal.documents- Each document in the response array contains aprocessingattribute. As long as processing is true the document has not finished being generated yet. Therefore, polling it required on this endpoint till all documents have been generated.affirmationStatement- The affirmation statement provided is required to be displayed to customer prior to them being able to affirm all documents.
Example of response payload
{
"legal": {
"documents": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Insurance Application",
"processing": true,
"url": "www.s3.legaldocurl-app.com"
},
{
"id": "c736e76c-d5fe-43b8-a5f8-0839f073f2dc",
"title": "E-delivery consent",
"processing": true,
"url": "www.s3.legaldocurl-delivery.com"
}
],
"affirmationStatement": {
"title": "Affirmation and Electronic Signature",
"statement": "I verify and confirm that I have read and agree to the document(s) above, that I own or lease the vehicle on this policy, and that I am the Named Insured on this policy and authorized to make selections of coverage. I understand that tapping 'Agree' below constitutes a legal signature confirming that I acknowledge and agree to the above Affirmation Statement."
}
}
}
11. Get [Specific] Legal Document
Once a document has been generated a customer can be redirected to a specific document to view via our GET endpoint.
It is not required for a customer to view each and every legal document, but they need to be given the opportunity to view them
GET: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/legal_documents/{id}
12. Affirm Legal Documents
Once a customer has had the opportunity to view all legal documents, they can acknowledge and affirm them. We use the timestamp this endpoint was called to indicate the when a customer affirmed.
POST: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/legal_documents
13. Generate Payment Token
Currently, only credit cards are an acceptable form of payment. To collect payment you'll need to generate a Braintree payment token here. For me detail on payment collection see Collection Payment Guide
POST: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/payment/braintree/client_token
14. Bind the Quote
Once a quote is finalize, affirmed and payment configured the customer is able to bind the policy here.
POST: https://{environment}.joinroot.com/bind_api/v3/quoting/quote/{quote_id}/bind
Updated about 1 month ago