> ## Documentation Index
> Fetch the complete documentation index at: https://portal.itscovered.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Flows

> Tips for the request flow in the Lenders API

# Comprehensive Insurance Verification

Through the Lenders API, you can ensure a borrower is insured, whether they're <Link href="#shopping-for-new-insurance">shopping for new insurance</Link> or <Link href="#retrieving-an-existing-policy">retrieving an existing policy</Link>.

<Note>
  <strong>Rate Limiting:</strong> The Lenders API implements rate limiting on certain endpoints. See our <Link href="/api-reference/rate_limits">Rate Limits</Link> documentation for details on current limits and best practices for handling rate limit responses.
</Note>

## Shopping for New Insurance

<Steps>
  <Step title="Authenticate">
    The first step is to authenticate. All endpoints require a valid access token.
    You can do this by using the <Link href="/api-reference/endpoint/get_auth_token">`POST /v1/auth/token`</Link> 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.
  </Step>

  <Step title="Submit Loan Application">
    The next step is to submit a loan application. This is done by using the <Link href="/api-reference/endpoint/submit_loan_application">`POST /v1/loans/application`</Link> endpoint.
    This endpoint will return a loan application ID. This ID is used to identify the loan application in all subsequent requests.
  </Step>

  <Step title="Consent">
    The next step is to record consent for the loan application and borrower. This is done by using the <Link href="/api-reference/endpoint/post_consent">`POST /v1/loans/consent`</Link> endpoint.
  </Step>

  <Step title="Shop Loan Application">
    The next step is to shop the loan application. This is done by using the <Link href="/api-reference/endpoint/shop_loan_application">`PATCH /v1/loans/shop`</Link> endpoint.
    This will initiate the quoting process which typically takes between 30-45 seconds.

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Receive Loan Shopped Webhook">
    When the shopping process is complete, and the loan application reaches
    `RC1_RATED` or `RC1_ERRORED`, you will receive a <Link href="/api-reference/webhooks#loan-application-shopped">`loan.shopped`</Link> 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.
  </Step>

  <Step title="Get Quote Display (User-Facing Results)">
    To display the quotes to your user in a polished, optimized way, use the <Link href="/api-reference/endpoint/get_quote_display">`GET /v1/loans/{id}/display`</Link> 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.
  </Step>

  <Step title="Select Quote">
    If your user selects a quote, you can record their selection by using the <Link href="/api-reference/endpoint/select_quote">`POST /v1/loans/{id}/quotes/{quoteId}/select`</Link> endpoint.
    This will record their selection and if you redirected them to Covered's quote display page, they will see the quote they selected.
  </Step>

  <Step title="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 <Link href="/api-reference/endpoint/schedule_call">`POST /v1/loans/schedule_call`</Link> endpoint
    or the <Link href="/api-reference/endpoint/call_me_now">`POST /v1/loans/call_me_now`</Link> 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.

    <Note>
      <strong>TCPA consent required:</strong> The loan application must have TCPA consent recorded before you can schedule a call or request a call me now event.
    </Note>
  </Step>

  <Step title="Receive Policy Bound Webhook">
    If the borrower decides to purchase a policy, you will receive a <Link href="/api-reference/webhooks#policy-bound">`policy.bound`</Link> 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.
  </Step>

  <Step title="Get Policy">
    The next step is to get the policy details. This is done by using the <Link href="/api-reference/endpoint/get_policy">`GET /v1/policies/{id}`</Link>
    endpoint.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Close Application (Lost) Signal">
    If the borrower decides to purchase a policy from another source, you can close the application by using the <Link href="/api-reference/endpoint/close_loan_application">`PATCH /v1/loans/{id}/close`</Link> 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.

    <Note>
      This step is optional and only needed if the borrower has obtained insurance from another source.
    </Note>
  </Step>
</Steps>

## Retrieving an Existing Policy

<Steps>
  <Step title="Authenticate">
    The first step is to authenticate. All endpoints require a valid access token.
    You can do this by using the <Link href="/api-reference/endpoint/get_auth_token">`POST /v1/auth/token`</Link> 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.
  </Step>

  <Step title="Submit Loan Application">
    The next step is to submit a loan application. This is done by using the <Link href="/api-reference/endpoint/submit_loan_application">`POST /v1/loans/application`</Link> endpoint.
    This endpoint will return a loan application ID. This ID is used to identify the loan application in all subsequent requests.
  </Step>

  <Step title="Initiate Policy Retrieval">
    The next step is to initiate the policy retrieval process. This is done by using the <Link href="/api-reference/endpoint/retrieve_policy">`PATCH /v1/policies/{id}/retrieve`</Link> 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.
  </Step>

  <Step title="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 |
  </Step>

  <Step title="Receive Policy Retrieved Webhook">
    If the borrower completes the policy retrieval process, you will receive a <Link href="/api-reference/webhooks#policy-retrieved">`policy.retrieved`</Link> webhook
    event.  You can use the policy ID from the webhook event in the next step to gather the policy details.
  </Step>

  <Step title="Get Policy">
    The next step is to get the policy details. This is done by using the <Link href="/api-reference/endpoint/get_policy">`GET /v1/policies/{id}`</Link>
    endpoint.
  </Step>

  <Step title="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.
  </Step>
</Steps>