NAV Navbar
examples
  • Ladder Platform Overview
  • Authentication
  • Quoters
  • Start an application
  • Ladder for Advisors
  • Calculator
  • Account Manager
  • Ladder Quote Widget
  • Errors
  • Ladder Platform Overview

    Welcome to the Ladder API documentation! Here you’ll find all the information you need to integrate with Ladder. The Ladder API provides access to a seamless integration for your users to acquire a term life insurance policy with Ladder and manage it over time.

    The Ladder API integration allows your users to:

    • Get and update a ballpark quote
    • Connect to the full application process
    • Calculate their life insurance needs
    • View and manage their policy over time

    You can choose which parts of the integration to utilize, depending on the context for your users’ experience.

    Ladder also offers the Ladder Quote Widget, a drop-in module that provides your users with the ability to get a ballpark quote within a pre-designed UI. The Widget handles input validation and error handling within the UI, as well.

    Authentication

    Ladder uses API keys for authentication. You can apply for a Ladder access key at api@ladderlife.com.

    To authorize your requests, use this code:

    # In the command line, you can just pass the correct header with each request
    curl "https://www.ladderlife.com/api/v1/..." \
      -H "Authorization: Bearer your-api-key" \
      -H "Content-Type: application/json"
    

    Make sure to replace your-api-key with your API key.

    All requests to the server must include the API key as a Bearer Token in the headers of the request.

    Authorization: Bearer your-api-key

    Quoters

    Many users overestimate the cost of life insurance. It can be helpful to provide them with a ballpark quote at the outset, before they complete a full application, to help estimate the cost of life insurance, given a few basic parameters. While the final price will depend on many specific health questions, the Quote can give users a directional sense for the cost. In most cases, the user’s final price is equal to their ballpark quote.

    The image below is a mock-up of what a quoter could look like when integrated with the Ladder API:

    Create a Quoter

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "mortgage" : 500000,
      "coverage" : 500000,
      "tobacco_use" : "never",
      "household_income" : 120000,
      "term" : 15,
      "external_id" : "12345678",
      "family_history" : false,
      "child_count" : 2,
      "weight_pounds" : 200,
      "date_of_birth" : "1980-11-24",
      "height_inches" : 69,
      "sex" : "male",
      "zipcode" : "94303"
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12",
      "quote_status" : {
        "complete" : true,
        "eligible" : true,
        "valid" : true
      },
      "quotes" : [ {
        "coverage" : 500000.0,
        "monthly_premium" : 29.27,
        "term" : 10.0,
        "daily_price" : 0.96
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 37.13,
        "term" : 15.0,
        "daily_price" : 1.22
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 47.2,
        "term" : 20.0,
        "daily_price" : 1.55
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 59.26,
        "term" : 25.0,
        "daily_price" : 1.94
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 76.13,
        "term" : 30.0,
        "daily_price" : 2.5
      } ]
    }
    

    This endpoint creates a quoter. The quoter's id is returned in the response, along with the validity of the input, and the quote results if the inputs are valid. If no quotes are returned, Ladder does not offer any coverage for the inputs.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/quoter

    Parameters

    Field Type Required Description
    height_inches number req User's height, in inches.
    household_income number req The user's annual household income in dollars represented by an integer ex: 90000.
    date_of_birth string req User's date of birth. Must be in the format yyyy-mm-dd.
    external_id string req The partner's unique identifier (external to Ladder) for a user.
    tobacco_use string req When the user has last used tobacco or a nicotine product. Possible values are never, within_last_12_months, 12_to_23_months, 24_to_35_months, and 36_months_or_greater.
    zipcode string req The zipcode of the user's residence, in a 5 number format.
    sex string req male, female or other (will need to specify later in the application process).
    weight_pounds number req User's weight, in pounds.
    family_history boolean req Biological parent or sibling diagnosed with cancer, diabetes, or heart disease before the age of 60.
    coverage number opt Amount of coverage in dollars a person wants to apply for. Defaults to 1M if not supplied. If supplied, it must be one of [100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 5500000, 6000000, 6500000, 7000000, 7500000, 8000000]
    dl_number string opt The user's driver's license number.
    dl_state string opt The abbreviation of the user's driver's license state as defined by USPS, ex: California => CA, Texas => TX, Hawaii => HI. (https://about.usps.com/who/profile/history/pdf/state-abbreviations.pdf)
    income number opt The user's annual income in dollars represented by an integer ex: 90000.
    email string opt The user's email.
    first_name string opt The user's first name.
    last_name string opt The user's last name.
    user_age number opt The user's age.
    phone string opt The user's phone number. Must be in the format XXX-XXX-XXXX
    street_address string opt The street address of the user's residence.
    city string opt The city in which the user resides.
    state string opt The state in which the user resides.
    term number opt Term lengths must be one of 10, 15, 20, 25, 30.
    lddr_creative string opt Name of advertising campaign, if any. Used only for reporting.
    family_history_members array opt Array of objects of type Family_member. See below for details.
    mortgage integer opt The amount remaining on the user's mortgage. If supplied, it must be one of [0, 100000, 200000, 300000, 400000, 500000, 600000, 700000, 800000, 900000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000]
    child_count integer opt The number of children the user has. If supplied, it must be one of [0, 1, 2, 3, 4, 5, 6]
    citizenship string opt Describes user's citizenship status. Possible values are us_citizen, us_permanent_resident, non_us_citizen.
    employment string opt Describes user's employment status. Possible values are employed, unemployed.

    Family_member

    Field Type Required Description
    relation string req Nested field for family_history_member; describes relationship of person to user applying for life insurance. Possible values are mother, father, sibling.
    condition string opt Nested field for family_history_member; describes medical condition of family member. Possible values are diabetes, cancer, heart_disease, huntingtons, and lynch_syndrome.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.
    quote_status object req Object of type Quote_status. See below for details.
    quotes array req Array of objects of type Quote. See below for details.

    Quote_status

    Field Type Required Description
    valid boolean req Indicates whether the minimum required fields are present.
    complete boolean req Indicates whether the quote is both valid and the user has selected a specific coverage amount and term length.
    eligible boolean req Whether the quoter is eligible for ladder coverage. If a quoter is ineligible, quotes he is eligible to, if any, are returned.

    Quote

    Field Type Required Description
    coverage number req The amount of coverage for this quote.
    monthly_premium number req The estimated monthly premium.
    daily_price number req The estimated daily price, based on monthly premium. When showing daily price, monthly premium must also be displayed. Please contact your Ladder representative before exposing any daily price to customers, so we can coordinate the display of the monthly premium. Doing this will ensure transparency and compliance with all requirements.
    term number req The term length in years.

    Retrieve a Quoter

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter/6099ae39-23f9-4b99-9223-f6e28d0aba12" \
       -H "Authorization: Bearer your-api-key" \
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12",
      "quote_status" : {
        "complete" : true,
        "eligible" : true,
        "valid" : true
      },
      "quotes" : [ {
        "coverage" : 500000.0,
        "monthly_premium" : 29.27,
        "term" : 10.0,
        "daily_price" : 0.96
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 37.13,
        "term" : 15.0,
        "daily_price" : 1.22
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 47.2,
        "term" : 20.0,
        "daily_price" : 1.55
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 59.26,
        "term" : 25.0,
        "daily_price" : 1.94
      }, {
        "coverage" : 500000.0,
        "monthly_premium" : 76.13,
        "term" : 30.0,
        "daily_price" : 2.5
      } ]
    }
    

    Once you have created a quoter, you can use this endpoint to retrieve the current quotes for the quoter.

    HTTP Request

    GET https://www.ladderlife.com/api/v1/quoter/:id

    This endpoint has no inputs.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.
    quote_status object req Object of type Quote_status. See below for details.
    quotes array req Array of objects of type Quote. See below for details.

    Quote_status

    Field Type Required Description
    valid boolean req Indicates whether the minimum required fields are present.
    complete boolean req Indicates whether the quote is both valid and the user has selected a specific coverage amount and term length.
    eligible boolean req Whether the quoter is eligible for ladder coverage. If a quoter is ineligible, quotes he is eligible to, if any, are returned.

    Quote

    Field Type Required Description
    coverage number req The amount of coverage for this quote.
    monthly_premium number req The estimated monthly premium.
    daily_price number req The estimated daily price, based on monthly premium. When showing daily price, monthly premium must also be displayed. Please contact your Ladder representative before exposing any daily price to customers, so we can coordinate the display of the monthly premium. Doing this will ensure transparency and compliance with all requirements.
    term number req The term length in years.

    Update a Quoter

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter/6099ae39-23f9-4b99-9223-f6e28d0aba12" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X PUT \
       -d \
    '{
      "coverage" : 1000000,
      "term" : 25
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12",
      "quote_status" : {
        "complete" : true,
        "eligible" : true,
        "valid" : true
      },
      "quotes" : [ {
        "coverage" : 1000000.0,
        "monthly_premium" : 52.03,
        "term" : 10.0,
        "daily_price" : 1.71
      }, {
        "coverage" : 1000000.0,
        "monthly_premium" : 67.13,
        "term" : 15.0,
        "daily_price" : 2.2
      }, {
        "coverage" : 1000000.0,
        "monthly_premium" : 86.64,
        "term" : 20.0,
        "daily_price" : 2.84
      }, {
        "coverage" : 1000000.0,
        "monthly_premium" : 109.07,
        "term" : 25.0,
        "daily_price" : 3.58
      }, {
        "coverage" : 1000000.0,
        "monthly_premium" : 141.14,
        "term" : 30.0,
        "daily_price" : 4.64
      } ]
    }
    

    Once you have created a quoter, you can use this endpoint to update the inputs for the quoter.

    The response produced by this endpoint includes the updated quote values for the quoter.

    HTTP Request

    PUT https://www.ladderlife.com/api/v1/quoter/:id

    Parameters

    Field Type Required Description
    zipcode string opt The zipcode of the user's residence, in a 5 number format.
    date_of_birth string opt User's date of birth. Must be in the format yyyy-mm-dd.
    coverage number opt Amount of coverage in dollars a person wants to apply for. Defaults to 1M if not supplied. If supplied, it must be one of [100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 5500000, 6000000, 6500000, 7000000, 7500000, 8000000]
    height_inches number opt User's height, in inches.
    weight_pounds number opt User's weight, in pounds.
    sex string opt male, female or other (will need to specify later in the application process).
    dl_number string opt The user's driver's license number.
    dl_state string opt The abbreviation of the user's driver's license state as defined by USPS, ex: California => CA, Texas => TX, Hawaii => HI. (https://about.usps.com/who/profile/history/pdf/state-abbreviations.pdf)
    income number opt The user's annual income in dollars represented by an integer ex: 90000.
    household_income number opt The user's annual household income in dollars represented by an integer ex: 90000.
    email string opt The user's email.
    family_history boolean opt Biological parent or sibling diagnosed with cancer, diabetes, or heart disease before the age of 60.
    first_name string opt The user's first name.
    last_name string opt The user's last name.
    user_age number opt The user's age.
    phone string opt The user's phone number. Must be in the format XXX-XXX-XXXX
    street_address string opt The street address of the user's residence.
    city string opt The city in which the user resides.
    state string opt The state in which the user resides.
    term number opt Term lengths must be one of 10, 15, 20, 25, 30.
    lddr_creative string opt Name of advertising campaign, if any. Used only for reporting.
    external_id string opt The partner's unique identifier (external to Ladder) for a user.
    family_history_members array opt Array of objects of type Family_member. See below for details.
    tobacco_use string opt When the user has last used tobacco or a nicotine product. Possible values are never, within_last_12_months, 12_to_23_months, 24_to_35_months, and 36_months_or_greater.
    mortgage integer opt The amount remaining on the user's mortgage. If supplied, it must be one of [0, 100000, 200000, 300000, 400000, 500000, 600000, 700000, 800000, 900000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000]
    child_count integer opt The number of children the user has. If supplied, it must be one of [0, 1, 2, 3, 4, 5, 6]
    citizenship string opt Describes user's citizenship status. Possible values are us_citizen, us_permanent_resident, non_us_citizen.
    employment string opt Describes user's employment status. Possible values are employed, unemployed.

    Family_member

    Field Type Required Description
    relation string req Nested field for family_history_member; describes relationship of person to user applying for life insurance. Possible values are mother, father, sibling.
    condition string opt Nested field for family_history_member; describes medical condition of family member. Possible values are diabetes, cancer, heart_disease, huntingtons, and lynch_syndrome.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.
    quote_status object req Object of type Quote_status. See below for details.
    quotes array req Array of objects of type Quote. See below for details.

    Quote_status

    Field Type Required Description
    valid boolean req Indicates whether the minimum required fields are present.
    complete boolean req Indicates whether the quote is both valid and the user has selected a specific coverage amount and term length.
    eligible boolean req Whether the quoter is eligible for ladder coverage. If a quoter is ineligible, quotes he is eligible to, if any, are returned.

    Quote

    Field Type Required Description
    coverage number req The amount of coverage for this quote.
    monthly_premium number req The estimated monthly premium.
    daily_price number req The estimated daily price, based on monthly premium. When showing daily price, monthly premium must also be displayed. Please contact your Ladder representative before exposing any daily price to customers, so we can coordinate the display of the monthly premium. Doing this will ensure transparency and compliance with all requirements.
    term number req The term length in years.

    Create interpolation

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter/6099ae39-23f9-4b99-9223-f6e28d0aba12/interpolate" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "events" : [ {
        "year" : 2020,
        "coverage" : 1500000
      }, {
        "year" : 2025,
        "coverage" : 1000000
      }, {
        "year" : 2030,
        "coverage" : 500000
      }, {
        "year" : 2035,
        "coverage" : 250000
      } ]
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12",
      "interpolation_status" : {
        "events_dropped" : false,
        "term_changed" : false
      },
      "suggested_messaging" : "Calculated based on an initial term length of 15 years and a coverage amount of $500,000.",
      "term" : 15,
      "coverage" : 500000,
      "yearly_quotes" : [ {
        "coverage" : 1500000,
        "monthly_premium" : 89.16,
        "year" : 2020,
        "daily_price" : 2.93
      }, {
        "coverage" : 1000000,
        "monthly_premium" : 63.15,
        "year" : 2025,
        "daily_price" : 2.07
      }, {
        "coverage" : 500000,
        "monthly_premium" : 37.13,
        "year" : 2030,
        "daily_price" : 1.22
      }, {
        "coverage" : 250000,
        "monthly_premium" : 18.57,
        "year" : 2035,
        "daily_price" : 0.61
      } ]
    }
    

    Use the data in a quoter and a list of laddering events to compute monthly premiums over time.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/quoter/:id/interpolate

    Parameters

    Field Type Required Description
    events array req Array of objects of type Yearly-coverage. See below for details.

    Yearly-coverage

    Field Type Required Description
    year number req The year for this ladder up/down.
    coverage number req Amount of coverage in dollars a person wants to apply for. Defaults to 1M if not supplied. If supplied, it must be one of [100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 5500000, 6000000, 6500000, 7000000, 7500000, 8000000]

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.
    term number req The term length in years.
    coverage number req The amount of coverage for this quote.
    suggested_messaging string req The suggested text to display to a user to explain the interpolation.
    interpolation_status object req Object of type Interpolation_status. See below for details.
    yearly_quotes array req Array of objects of type Yearly-quote. See below for details.

    Interpolation_status

    Field Type Required Description
    term_changed boolean req Whether or not the quote term is different than the interpolated term.
    events_dropped boolean req Whether or not any of the input events were dropped/truncated from result. They will be set to 0 if so.

    Yearly-quote

    Field Type Required Description
    year number req The year for this quote.
    coverage number req The amount of coverage for this quote.
    daily_price number req The estimated daily price, based on monthly premium. When showing daily price, monthly premium must also be displayed. Please contact your Ladder representative before exposing any daily price to customers, so we can coordinate the display of the monthly premium. Doing this will ensure transparency and compliance with all requirements.
    monthly_premium number req The estimated monthly premium.

    Get Bundles

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter/6099ae39-23f9-4b99-9223-f6e28d0aba12/bundles" \
       -H "Authorization: Bearer your-api-key" \
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12",
      "bundles" : {
        "recommended_for_you" : {
          "coverage" : 1000000.0,
          "term" : 20.0,
          "label" : "Recommended for you",
          "bundle_name" : "recommended_for_you"
        }
      }
    }
    

    Retrieve the most popular coverage amount and term length for a given quoter object.

    HTTP Request

    GET https://www.ladderlife.com/api/v1/quoter/:id/bundles

    This endpoint has no inputs.

    HTTP Response

    Field Type Required Description
    bundles object req Object of type Bundles. See below for details.

    Bundles

    Field Type Required Description
    most_popular object opt Object of type Most_popular. See below for details.
    Field Type Required Description
    coverage number req The amount of coverage for this quote.
    term number req The term length in years.
    label string req Human friendly string to explain the bundle.
    bundle_name string req Bundle name

    Start an application

    Use these endpoints to start an application for a user, or invite them to start one themselves.

    Redirect user to Ladder

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter/6099ae39-23f9-4b99-9223-f6e28d0aba12/apply" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "email" : "email@example.com",
      "first_name" : "Edmond",
      "last_name" : "Halley"
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12",
      "url" : "https://www.ladderlife.com/api/v1/redirect/...",
      "url_expires" : 1577840417
    }
    

    Once your user has a quote through the Ladder API and/or the Ladder Quote Widget (documentation below), they are able to apply for instant coverage through Ladder's application.

    This endpoint should be used to set up a HTTP status 302 redirect to the url returned by the API.

    The Ladder Connector creates a smooth quote‑to‑application flow by redirecting the user from your site to the Ladder application. Ladder will land the user on the appropriate page, given their quote status (and the quote status does not need to be valid or complete to use the Ladder Connector).

    For the best user experience, include more quote fields so that Ladder may land the user further along in the process. The Connector is designed to increase your conversions.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/quoter/:id/apply

    Parameters

    Field Type Required Description
    zipcode string opt The zipcode of the user's residence, in a 5 number format.
    date_of_birth string opt User's date of birth. Must be in the format yyyy-mm-dd.
    coverage number opt Amount of coverage in dollars a person wants to apply for. Defaults to 1M if not supplied. If supplied, it must be one of [100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 5500000, 6000000, 6500000, 7000000, 7500000, 8000000]
    height_inches number opt User's height, in inches.
    weight_pounds number opt User's weight, in pounds.
    sex string opt male, female or other (will need to specify later in the application process).
    dl_number string opt The user's driver's license number.
    dl_state string opt The abbreviation of the user's driver's license state as defined by USPS, ex: California => CA, Texas => TX, Hawaii => HI. (https://about.usps.com/who/profile/history/pdf/state-abbreviations.pdf)
    income number opt The user's annual income in dollars represented by an integer ex: 90000.
    household_income number opt The user's annual household income in dollars represented by an integer ex: 90000.
    email string opt The user's email.
    family_history boolean opt Biological parent or sibling diagnosed with cancer, diabetes, or heart disease before the age of 60.
    first_name string opt The user's first name.
    last_name string opt The user's last name.
    user_age number opt The user's age.
    phone string opt The user's phone number. Must be in the format XXX-XXX-XXXX
    street_address string opt The street address of the user's residence.
    city string opt The city in which the user resides.
    state string opt The state in which the user resides.
    term number opt Term lengths must be one of 10, 15, 20, 25, 30.
    lddr_creative string opt Name of advertising campaign, if any. Used only for reporting.
    external_id string opt The partner's unique identifier (external to Ladder) for a user.
    family_history_members array opt Array of objects of type Family_member. See below for details.
    tobacco_use string opt When the user has last used tobacco or a nicotine product. Possible values are never, within_last_12_months, 12_to_23_months, 24_to_35_months, and 36_months_or_greater.
    mortgage integer opt The amount remaining on the user's mortgage. If supplied, it must be one of [0, 100000, 200000, 300000, 400000, 500000, 600000, 700000, 800000, 900000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000]
    child_count integer opt The number of children the user has. If supplied, it must be one of [0, 1, 2, 3, 4, 5, 6]
    citizenship string opt Describes user's citizenship status. Possible values are us_citizen, us_permanent_resident, non_us_citizen.
    employment string opt Describes user's employment status. Possible values are employed, unemployed.

    Family_member

    Field Type Required Description
    relation string req Nested field for family_history_member; describes relationship of person to user applying for life insurance. Possible values are mother, father, sibling.
    condition string opt Nested field for family_history_member; describes medical condition of family member. Possible values are diabetes, cancer, heart_disease, huntingtons, and lynch_syndrome.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.
    url string req The url to load to show the user their application process.
    url_expires number req Time at which the url expires. Measured in seconds since the Unix epoch.

    Invite user via email

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/quoter/6099ae39-23f9-4b99-9223-f6e28d0aba12/invite" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "email" : "email@example.com",
      "first_name" : "Edmond",
      "last_name" : "Halley",
      "advisor_id" : "c9bdda65-ce6e-486e-b914-7cb491936a21"
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12"
    }
    

    Similar to the /apply endpoint above, but specifically for Ladder for Advisors use cases.

    Requires an advisor_id param, and sends the client an email inviting them to start an application. No redirect URL is provided in the response, unlike the apply endpoint.

    If no user email was ever provided, or if the advisor_id was invalid, returns a 400.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/quoter/:id/invite

    Parameters

    Field Type Required Description
    advisor_id string req Advisor that referred this user, for attribution.
    zipcode string opt The zipcode of the user's residence, in a 5 number format.
    date_of_birth string opt User's date of birth. Must be in the format yyyy-mm-dd.
    coverage number opt Amount of coverage in dollars a person wants to apply for. Defaults to 1M if not supplied. If supplied, it must be one of [100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000, 550000, 600000, 650000, 700000, 750000, 800000, 850000, 900000, 950000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000, 2250000, 2500000, 2750000, 3000000, 3250000, 3500000, 3750000, 4000000, 4250000, 4500000, 4750000, 5000000, 5500000, 6000000, 6500000, 7000000, 7500000, 8000000]
    height_inches number opt User's height, in inches.
    weight_pounds number opt User's weight, in pounds.
    sex string opt male, female or other (will need to specify later in the application process).
    dl_number string opt The user's driver's license number.
    dl_state string opt The abbreviation of the user's driver's license state as defined by USPS, ex: California => CA, Texas => TX, Hawaii => HI. (https://about.usps.com/who/profile/history/pdf/state-abbreviations.pdf)
    income number opt The user's annual income in dollars represented by an integer ex: 90000.
    household_income number opt The user's annual household income in dollars represented by an integer ex: 90000.
    email string opt The user's email.
    family_history boolean opt Biological parent or sibling diagnosed with cancer, diabetes, or heart disease before the age of 60.
    first_name string opt The user's first name.
    last_name string opt The user's last name.
    user_age number opt The user's age.
    phone string opt The user's phone number. Must be in the format XXX-XXX-XXXX
    street_address string opt The street address of the user's residence.
    city string opt The city in which the user resides.
    state string opt The state in which the user resides.
    term number opt Term lengths must be one of 10, 15, 20, 25, 30.
    lddr_creative string opt Name of advertising campaign, if any. Used only for reporting.
    external_id string opt The partner's unique identifier (external to Ladder) for a user.
    family_history_members array opt Array of objects of type Family_member. See below for details.
    tobacco_use string opt When the user has last used tobacco or a nicotine product. Possible values are never, within_last_12_months, 12_to_23_months, 24_to_35_months, and 36_months_or_greater.
    mortgage integer opt The amount remaining on the user's mortgage. If supplied, it must be one of [0, 100000, 200000, 300000, 400000, 500000, 600000, 700000, 800000, 900000, 1000000, 1100000, 1200000, 1300000, 1400000, 1500000, 1600000, 1700000, 1800000, 1900000, 2000000]
    child_count integer opt The number of children the user has. If supplied, it must be one of [0, 1, 2, 3, 4, 5, 6]
    citizenship string opt Describes user's citizenship status. Possible values are us_citizen, us_permanent_resident, non_us_citizen.
    employment string opt Describes user's employment status. Possible values are employed, unemployed.

    Family_member

    Field Type Required Description
    relation string req Nested field for family_history_member; describes relationship of person to user applying for life insurance. Possible values are mother, father, sibling.
    condition string opt Nested field for family_history_member; describes medical condition of family member. Possible values are diabetes, cancer, heart_disease, huntingtons, and lynch_syndrome.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.

    Ladder for Advisors

    Use these endpoints to integrate your application with the Ladder for Advisors program.

    Register an advisor

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/lfa/register" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "email" : "financial_advisor@ladderlife.com",
      "first_name" : "Edmond",
      "last_name" : "Halley"
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12"
    }
    

    Create a Ladder for Advisors account for a financial advisor.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/lfa/register

    Parameters

    Field Type Required Description
    email string req The user's email.
    first_name string req The user's first name.
    last_name string req The user's last name.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.

    Find an advisor

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/lfa/find" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -d \
    '{
      "email" : "financial_advisor@ladderlife.com"
    }'
    

    Example Responses:

    {
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12"
    }
    

    Get the user ID of a Ladder for Advisors account given its associated email address

    HTTP Request

    GET https://www.ladderlife.com/api/v1/lfa/find

    Parameters

    Field Type Required Description
    email string req The user's email.

    HTTP Response

    Field Type Required Description
    id string req The generated identifier for the returned quoter. It is valid indefinitely.

    Login as a financial advisor

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/lfa/login" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "email" : "financial_advisor@ladderlife.com",
      "id" : "6099ae39-23f9-4b99-9223-f6e28d0aba12"
    }'
    

    Example Responses:

    {
      "ok" : true
    }
    

    Sends an email with a login link to a Ladder for Advisors account holder given an associated user-id or email address. A successful request will simply return {"ok" : true}, and a login email will be sent to the associated account. Note that this endpoint can only be used to generate login emails for users enrolled as financial advisors in the Ladder for Advisors program, and will not work for other Ladder users or policyholders.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/lfa/login

    Parameters

    Field Type Required Description
    id string opt The generated identifier for the returned quoter returned from creating a quoter.
    email string opt The user's email.

    HTTP Response

    Field Type Required Description

    Calculator

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/calculator" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "children_education_tuition" : 20000,
      "additional_coverage" : 0,
      "children" : [ {
        "age" : 0
      }, {
        "age" : 5
      }, {
        "age" : 9
      } ],
      "desired_payout_years" : 15,
      "existing_coverage" : 0,
      "other_debts" : 50000,
      "desired_yearly_cash" : 80000,
      "current_savings" : 100000,
      "mortgage_balance" : 200000
    }'
    

    Example Responses:

    {
      "additional_coverage" : 0,
      "current_resources" : -100000,
      "debt" : 250000,
      "living_expenses" : 955034,
      "nearest_policy" : 1600000,
      "nearest_term_length" : 25,
      "total_insurance_needs" : 1531943,
      "tuition_costs" : 426908
    }
    

    The needs calculator helps a user figure out how much coverage they need. It is not a required part of the process, but it can be helpful to them, depending on your context.

    The following image is a mock-up of what a calculator might look like when integrated with the Ladder API:

    HTTP Request

    POST https://www.ladderlife.com/api/v1/calculator

    Parameters

    Field Type Required Description
    mortgage_balance integer opt The user's estimated mortgage balance.
    other_debts integer opt The user's estimated other debts.
    children array opt Array of objects of type Child. See below for details.
    children_education_tuition integer opt Average yearly college cost for a child.
    desired_yearly_cash integer opt The user's desired cash payout to their beneficiaries.
    desired_payout_years integer opt The user's desired number of cash payout years to their beneficiaries.
    additional_coverage integer opt Additionnal needs. The user's additional coverage desired.
    existing_coverage integer opt The user's existing life insurance coverage.
    current_savings integer opt The user's estimated current total savings.

    Child

    Field Type Required Description
    age integer req The child's age in years.

    HTTP Response

    Field Type Required Description
    debt integer req Debt.
    current_resources integer req Current resources. Includes savings and current life insurance.
    living_expenses integer req Living expenses. Lump sum to provide the annual amounts chosen for beneficiaries.
    tuition_costs integer req Children’s education. Estimate of what college will cost for the children.
    additional_coverage integer req Additionnal needs. The user's additional coverage desired.
    total_insurance_needs integer req Total life insurance needs.
    nearest_policy integer req Nearest available coverage offered by Ladder (amount can be reused to create a quoter)

    Account Manager

    The Account Manager allows you to retrieve policy information for users who applied through your platform. You can also give them the ability to reduce their coverage over time.

    Policy Information

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/management/6099ae39-23f9-4b99-9223-f6e28d0aba12" \
       -H "Authorization: Bearer your-api-key" \
    

    Example Responses:

    {
      "active_policies" : [ {
        "policy_id" : "TN-784",
        "active_coverage" : 350000,
        "active_term" : 20,
        "active_monthly_premium" : 34.12,
        "ladder_down_prices" : [ {
          "new_coverage" : 100000,
          "new_monthly_premium" : 8.69
        }, {
          "new_coverage" : 150000,
          "new_monthly_premium" : 9.88
        }, {
          "new_coverage" : 200000,
          "new_monthly_premium" : 11.24
        }, {
          "new_coverage" : 250000,
          "new_monthly_premium" : 12.79
        }, {
          "new_coverage" : 300000,
          "new_monthly_premium" : 13.99
        }, {
          "new_coverage" : 350000,
          "new_monthly_premium" : 15.3
        } ]
      } ]
    }
    

    The management API allows you to retrieve coverage information for users that applied through your platform.

    HTTP Request

    GET https://www.ladderlife.com/api/v1/management/:id

    This endpoint has no inputs.

    HTTP Response

    Field Type Required Description
    active_policies array req Array of objects of type Policy. See below for details.

    Policy

    Field Type Required Description
    policy_id string req The ID of the policy issued.
    active_coverage number req The policy's coverage amount.
    active_term number req The policy's term length in years.
    active_monthly_premium number req The policy's monthly premium.
    ladder_down_prices array req Array of objects of type Ladder_down_price. See below for details.

    Ladder_down_price

    Field Type Required Description
    new_monthly_premium number req New monthly premium to be paid.
    new_coverage number req New coverage amount for the policy.

    Laddering Down

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/management/6099ae39-23f9-4b99-9223-f6e28d0aba12/ladder-down/TN-784" \
       -H "Authorization: Bearer your-api-key" \
       -H "Content-Type: application/json" \
       -X POST \
       -d \
    '{
      "new_coverage" : 300000,
      "new_monthly_premium" : 13.99
    }'
    

    Example Responses:

    {
      "active_policies" : [ {
        "policy_id" : "TN-784",
        "active_coverage" : 300000,
        "active_term" : 20,
        "active_monthly_premium" : 13.99,
        "ladder_down_prices" : [ {
          "new_coverage" : 100000,
          "new_monthly_premium" : 8.69
        }, {
          "new_coverage" : 150000,
          "new_monthly_premium" : 9.88
        }, {
          "new_coverage" : 200000,
          "new_monthly_premium" : 11.24
        }, {
          "new_coverage" : 250000,
          "new_monthly_premium" : 12.79
        }, {
          "new_coverage" : 300000,
          "new_monthly_premium" : 13.99
        } ]
      } ]
    }
    

    This endpoint allows the user to ladder down a policy (decrease coverage). The input parameters must be a ladder_down_price that was returned from the Account Manager GET call.

    HTTP Request

    POST https://www.ladderlife.com/api/v1/management/:id/ladder-down/:policy-id

    Parameters

    Field Type Required Description
    new_monthly_premium number req New monthly premium to be paid.
    new_coverage number req New coverage amount for the policy.

    HTTP Response

    Field Type Required Description
    active_policies array req Array of objects of type Policy. See below for details.

    Policy

    Field Type Required Description
    policy_id string req The ID of the policy issued.
    active_coverage number req The policy's coverage amount.
    active_term number req The policy's term length in years.
    active_monthly_premium number req The policy's monthly premium.
    ladder_down_prices array req Array of objects of type Ladder_down_price. See below for details.

    Ladder_down_price

    Field Type Required Description
    new_monthly_premium number req New monthly premium to be paid.
    new_coverage number req New coverage amount for the policy.

    Application Status

    Example Request:

    $ curl "https://www.ladderlife.com/api/v1/management/6099ae39-23f9-4b99-9223-f6e28d0aba12/status" \
       -H "Authorization: Bearer your-api-key" \
    

    Example Responses:

    {
      "status" : "application_not_started",
      "suggested_messaging" : {
        "title" : "Now's the time for life insurance",
        "subtitle" : "Find out if you're instantly approved for coverage.",
        "call_to_action" : "Get started with Ladder",
        "alternative_call_to_action" : "Get started"
      }
    }
    
    {
      "status" : "application_incomplete",
      "suggested_messaging" : {
        "title" : "Finish your life insurance application?",
        "subtitle" : "It takes 5 minutes, and you'll find out if you're instantly improved."
      },
      "ineligibility" : {
        "is_eligible" : true
      },
      "quote_questions_answered" : [ "email", "residence_state", "gender", "height_inches", "weight_pounds", "smoker", "date_of_birth", "household_income", "number_of_children", "mortgage_balance" ]
    }
    
    {
      "status" : "application_incomplete_fallback_shown",
      "suggested_messaging" : {
        "title" : "We found you a better fit",
        "subtitle" : "We may not have the right life insurance for you. We found popular options that are likely to be a better match."
      },
      "ineligibility" : {
        "is_eligible" : true
      },
      "quote_questions_answered" : [ "gender", "height_inches", "weight_pounds", "date_of_birth", "term", "coverage", "residence_state", "zipcode", "name", "email", "smoker", "family_history", "household_income", "number_of_children", "mortgage_balance" ]
    }
    
    {
      "status" : "application_complete_action_needed",
      "suggested_messaging" : {
        "title" : "There's a bit more to do. Take care of it now?",
        "subtitle" : "Finishing up now will allow Ladder, our trusted life insurance partner, to continue reviewing your application."
      }
    }
    
    {
      "status" : "application_complete_pending_underwriting",
      "suggested_messaging" : {
        "title" : "Check out your Ladder account page?",
        "subtitle" : "There’s no action you need to take, but feel free to explore."
      }
    }
    
    {
      "status" : "offer_pending",
      "suggested_messaging" : {
        "title" : "You’ve been approved! Accept your life insurance policy now?",
        "subtitle" : "Congrats! Your coverage will begin when you accept your policy and authorize payment."
      },
      "offer_details" : {
        "face_amount" : 500000.0,
        "monthly_premium" : 14.07,
        "term" : 10,
        "expires_unix" : 1687455140
      }
    }
    
    {
      "status" : "covered",
      "suggested_messaging" : {
        "title" : "You have a policy! Ready to get your account up to date?",
        "subtitle" : "Add a beneficiary, for example. It’ll only take a moment."
      },
      "policy_details" : {
        "id" : "TL-146-2433-1B43F500T10X1",
        "face_amount" : 50000.0,
        "monthly_premium" : 34.12,
        "term" : 10,
        "issue_timestamp" : 1687455140
      }
    }
    
    {
      "status" : "application_closed",
      "suggested_messaging" : {
        "title" : "Reapply for life insurance?",
        "subtitle" : "It’s not too late to reapply for coverage with Ladder, our trusted life insurance partner."
      }
    }
    
    {
      "status" : "policy_canceled",
      "suggested_messaging" : {
        "title" : "Your policy was canceled",
        "subtitle" : "For more information, please contact support@ladderlife.com"
      }
    }
    
    {
      "status" : "application_declined",
      "suggested_messaging" : {
        "title" : "We’re sorry",
        "subtitle" : "Unfortunately, Ladder is unable to offer you coverage at this time."
      }
    }
    

    This endpoint fetches the status of a user's application and offer.

    HTTP Request

    GET https://www.ladderlife.com/api/v1/management/:id/status

    This endpoint has no inputs.

    HTTP Response

    Field Type Required Description
    status string req The application's current status. Possible values are application_not_started, application_incomplete, application_incomplete_fallback_shown, application_complete_action_needed, application_complete_pending_underwriting, offer_pending, covered, application_closed, application_declined.
    suggested_messaging object opt Object of type Suggested_messaging. See below for details.

    Suggested_messaging

    Field Type Required Description
    title string req A suggested title for the application's current status
    subtitle string req A suggested subtitle for the application's current status

    Application Status Webhook

    The Ladder Application Status Webhook allows your application to receive updates for the status of users' applications.

    The statuses that are pushed from Ladder match the ones described in Application Status.

    Example request body from Ladder to your URL

    {
      "status": "application_incomplete",
      "suggested_messaging": {
        "title": "Finish your life insurance application?",
        "subtitle": "It takes 5 minutes, and you'll find out if you're instantly approved."
      },
      "ineligibility": {
        "is_eligible": true
      },
      "quote_questions_answered": [
        "gender",
        "date_of_birth",
        "term",
        "coverage",
        "residence_state",
        "name",
        "email",
        "height_inches",
        "weight_pounds",
        "smoker",
        "family_history",
        "household_income",
        "number_of_children",
        "mortgage_balance"
      ],
      "id": "cf521091-615e-4f3c-a574-251e2a02c69a",
      "external_id": "22222-8fe6-443a-8f31-abc12345",
      "request_time": 1577836902
    }
    

    Example signature in request header

    "X-API-Key: XGTysGfIdo563vQ8Tn0ckhjz1CivMEH/3Y4YVAxn8cQ="
    

    Technical Details

    These are all the possible values under quote_questions_answered.

    Fields
    email
    weight_pounds
    nicotine_use
    smoker
    height_inches
    name
    coverage
    number_of_children
    zipcode
    date_of_birth
    residence_state
    activity_level
    term
    family_history_members
    mortgage_balance
    household_income
    gender
    family_history

    Example pseudo-code to validate the request body

    key = base64_decode(base64_encoded_key)
    request_bytes = utf8_str_to_bytes(request_body)
    Signature = base64_encode(hmac_sha256(key, request_bytes))
    ValidRequest = (Signature == get(request_headers, "X-API-Key"))
    

    Ladder Quote Widget

    Now that you know the basics of the Ladder API and have an API key, you can integrate with the Ladder Quote Widget for a quick set up. The Ladder Quote Widget is a drop-in module that handles input validation and error handling within the UI.

    Integrating with the Ladder Quote Widget takes only a few lines of client-side HTML. The next section has a working example of each available widget type along with the exact HTML needed to embed it in your page.

    After filling out the input fields, the user can click "Get My Quote" to see quick estimate of what their rate could be for the default coverage of $1 Million and default term length of 20 years. Clicking "Get Started" will direct the user to www.ladderlife.com where they can begin an application and customize their quote further. Feel free to try this out with any of the widgets below.

    ladder-widget-tile-a

    Width: 300px, height: 250px

    <div class="ladder-widget-tile-a"></div>
    <script src="https://www.ladderlife.com/widget/embed.js"></script>
    

    ladder-widget-tile-b

    Width: 336px, height: 280px

    <div class="ladder-widget-tile-b"></div>
    <script src="https://www.ladderlife.com/widget/embed.js"></script>
    

    ladder-widget-portrait

    Width: 420px, height: 623px

    <div class="ladder-widget-portrait"></div>
    <script src="https://www.ladderlife.com/widget/embed.js"></script>
    

    ladder-widget-flex-portrait

    As above, but will shrink to fit its container down to a minimum width of 259px and a minimum height of 458px. Unlike the non-flex version, this widget requires that the containing div have its height set, and optionally its width too.

    <style>
    .ladder-widget-flex-portrait { width:320px; height:568px; }
    </style>
    <div class="ladder-widget-flex-portrait"></div>
    <script src="https://www.ladderlife.com/widget/embed.js"></script>
    

    ladder-widget-landscape

    Width: 720px, height: 377px

    <div class="ladder-widget-landscape"></div>
    <script src="https://www.ladderlife.com/widget/embed.js"></script>
    

    Errors

    The Ladder API always returns JSON for valid requests. Plain text will be returned for invalid requests. The following codes will be returned:

    HTTP Code Meaning
    200 Success
    400 Bad Request — Invalid.
    401 Unauthorized — Missing or invalid API key.
    403 Forbidden — Account does not have permission to access endpoint.
    404 Not Found — Endpoint does not exist.
    429 Too Many Requests — You've issued more requests than what Ladder allows in a period of time.
    500 Internal Server Error — Ladder server problem. Please try again later.
    503 Service Unavailable — Temporarily offline for maintenance. Please try again later.