Comprehensive Insurance Verification
Through the Lenders API, you can ensure a borrower is insured, whether they’re shopping for new insurance or retrieving an existing policy.Rate Limiting: The Lenders API implements rate limiting on certain endpoints. See our Rate Limits documentation for details on current limits and best practices for handling rate limit responses.
Shopping for New Insurance
Authenticate
The first step is to authenticate. All endpoints require a valid access token.
You can do this by using the
POST /v1/auth/token endpoint using your client ID and secret.
If you are a Platform Partner, meaning you have many different lender clients on your platform, you must also provide a partner_id in the request body.
Platform partners will need to make an authentication request for each lender client, as each token will be scoped specifically to the lender client.
Standard API partners do not need to provide this.
The response will be a JSON object with an access_token and expires_in property. Token expiration is 24 hours. Please only request a new token when the current one is expired.Submit Loan Application
The next step is to submit a loan application. This is done by using the
POST /v1/loans/application endpoint.
This endpoint will return a loan application ID. This ID is used to identify the loan application in all subsequent requests.Consent
The next step is to record consent for the loan application and borrower. This is done by using the
POST /v1/loans/consent endpoint.Shop Loan Application
The next step is to shop the loan application. This is done by using the
PATCH /v1/loans/shop endpoint.
This will initiate the quoting process which typically takes between 30-45 seconds.For testing purposes, if the
firstName of the primary borrower is set to Bind_policy and the loan is shopped in the sandbox environment, a policy will automatically be created and associated to the contact.
Additionally, if the lastName of the primary borrower is set to Wind, Dwelling_fire, Flood, or Earthquake, a supplemental policy will also be created in the same line of business and associated to the contact.Receive Loan Shopped Webhook
When the shopping process is complete, and the loan application reaches
RC1_RATED or RC1_ERRORED, you will receive a loan.shopped webhook event
to notify you that the loan application has been shopped. After receiving
this webhook, you proceed to reading the shopping results in the next step.Get Quote Display (User-Facing Results)
To display the quotes to your user in a polished, optimized way, use the
GET /v1/loans/{id}/display endpoint.
This endpoint returns quotes formatted specifically for user-facing display, with only the quotes we recommend showing selected and ready for presentation.
If your user has already selected a quote, this endpoint will also indicate which one was selected.
This endpoint handles the presentation logic so you can focus on the user experience.Select Quote
If your user selects a quote, you can record their selection by using the
POST /v1/loans/{id}/quotes/{quoteId}/select endpoint.
This will record their selection and if you redirected them to Covered’s quote display page, they will see the quote they selected.Call Me Now and Schedule Call
The next step would be to schedule a call with the borrower or call them immediately.
This is done by using the
POST /v1/loans/schedule_call endpoint
or the POST /v1/loans/call_me_now endpoint.
Scheduling a call will create a task in our system for one of our Advisors to call the borrower at the specified date/time.
Making a call me now request will notify an Advisor to contact the borrower immediately.TCPA consent required: The loan application must have TCPA consent recorded before you can schedule a call or request a call me now event.
Receive Policy Bound Webhook
If the borrower decides to purchase a policy, you will receive a
policy.bound webhook event
to notify you that the policy has been bound. You can use the policy
ID from the webhook event in the next step.Get Policy
The next step is to get the policy details. This is done by using the
GET /v1/policies/{id}
endpoint.Download Policy Documents
The policy details includes a list of documents that are associated with the policy. You can download these documents by using the
signed URL for the document. These URLs expire after a short period of time, so you should download the documents right after you receive the policy details.
Close Application (Lost) Signal
If the borrower decides to purchase a policy from another source, you can close the application by using the
PATCH /v1/loans/{id}/close endpoint.
This will update the loan application status to CLOSED_LOST and notify the system that the borrower has obtained insurance elsewhere.
This is useful for tracking purposes and to ensure that the loan application is not shopped again.This step is optional and only needed if the borrower has obtained insurance from another source.
Retrieving an Existing Policy
Authenticate
The first step is to authenticate. All endpoints require a valid access token.
You can do this by using the
POST /v1/auth/token endpoint using your client ID and secret.
If you are a Platform Partner, meaning you have many different lender clients on your platform, you must also provide a partner_id in the request body.
Platform partners will need to make an authentication request for each lender client, as each token will be scoped specifically to the lender client.
Standard API partners do not need to provide this.
The response will be a JSON object with an access_token and expires_in property. Token expiration is 24 hours. Please only request a new token when the current one is expired.Submit Loan Application
The next step is to submit a loan application. This is done by using the
POST /v1/loans/application endpoint.
This endpoint will return a loan application ID. This ID is used to identify the loan application in all subsequent requests.Initiate Policy Retrieval
The next step is to initiate the policy retrieval process. This is done by using the
PATCH /v1/policies/{id}/retrieve endpoint.
Your response will include a URL to guide the user to our policy retrieve experience, where they can enter their carrier credentials to retrieve their existing policy.SANDBOX - Retrieve a Fake Policy
In the sandbox environment, you can retrieve a fake policy by selecting any carrier and entering any of the following special credentials:
| Username | Password | Outcome |
|---|---|---|
| user_good | pass_good | A home policy |
| user_good_flood | pass_good | A home and flood policy |
| user_good_expensive | pass_good | A home policy with a high premium |
Receive Policy Retrieved Webhook
If the borrower completes the policy retrieval process, you will receive a
policy.retrieved webhook
event. You can use the policy ID from the webhook event in the next step to gather the policy details.Get Policy
The next step is to get the policy details. This is done by using the
GET /v1/policies/{id}
endpoint.Download Policy Documents
The policy details includes a list of documents that are associated with the policy. You can download these documents by using the
signed URL for the document. These URLs expire after a short period of time, so you should download the documents right after you receive the policy details.