Overview

The Application API is a REST API which allows simple access to life insurance applications, decisions, and policies. It uses standard HTTP codes, accepts JSON parameters, and returns JSON responses.

Standard documentation on Ladder’s API can be found here. Below, you’ll find the additional information you need to integrate with Ladder’s Application API. The Ladder Application API provides select partners access to a seamless integration for your users to apply for a term life insurance policy with Ladder.

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

Authentication

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

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

Quick start

A typical user flow will look like the following:

Create a quote using the Quoter API.
Create an application.
Answer questions until next_incomplete_question returns null.
Sign the application.
Wait for Ladder to make a decision on the application.
Set user payment using Ladder's Javascript SDK.
Retrieve and accept the offer.
Retrieve the user's new term life insurance policy!.

Progressive enhancement

The Ladder API is designed such that at any point, you can pass the applicant to the Ladder site to continue their application. This can be useful in cases like ID verification failure or applicant ineligibility.

This can be achieved by retrieving a Ladder redirect link and redirecting the applicant to that link.

API Version

The Application API is on version 2. Requests to the Application API should begin with https://www.ladderlife.com/api/v2/. Note that the Quoter API is still on version 1, and that requests to the Quoter API should begin with https://www.ladderlife.com/api/v1/.

Errors

The Application API may return errors for any API call. In general, 2xx response codes are successful requests, 4xx codes signify client-side errors, and 5xx codes signify server-side errors. Along with the HTTP response code, the Application API will also generally return JSON-encoded dictionaries of error objects. All endpoints may return the following errors:

HTTP Code	Error Type	Description
400	User error	An invalid API call was made, or invalid argument was passed.
401	Unauthenticated	The caller didn't provide any credentials, or the credentials were invalid.
403	Unauthorized	The caller's credentials were valid, but don't grant permission to the requested resource.
404	Not found	The requested resource was not found.
429	Throttled	Too many requests were made in a short period of time.
500-599	N/A	Internal server error.

Error object

{
  "type" : "failed_validation",
  "message" : "Must be positive",
  "details" : { }
}

Field	Type	Nullable	Description
`type`	`string`		The error type.
`message`	`string`	Yes	A descriptive message of the error, that can be shared with the user.
`details`	`dict`	Yes	A dictionary containing error details, if any.

Ladder JavaScript SDK

Ladder provides a Javascript SDK for certain sensitive customer inputs. The SDK creates a hosted field such that the customer's data never touches your servers

The JavaScript SDK requires a per-user token for instantiation. Tokens expire after 1 day.

Instantiating the Ladder SDK

To start, add our JavaScript script to your webpage:

<script src="https://www.ladderlife.com/api/v2/js/main.js"></script>

Next, instantiate a Ladder API object. You will need a per-user token that can be fetched from your server and passed into your webpage.

const ladderApi = new LadderAPI("YourTokenHere");

Now, you can use the Ladder SDK to answer questions requiring a hosted field and to accept payment.

SDK Interface

declare class LadderAPI {
    constructor(pubToken: string)
    payment(): LadderAPILib.PaymentOperations;
    application(appId: string): LadderAPILib.ApplicationOperations;
}

declare namespace LadderAPILib {
    // Application
    declare class ApplicationOperations {
        createQuestionElement(questionId: string, options?: QuestionOptions): QuestionElement;
    }

    enum QuestionEventType {
        CHANGE = "change",
        ERROR = "error"
    }

    declare class QuestionElement {
        on(event: QuestionEventType, callback: QuestionElementChangeHandler | QuestionElementErrorHandler): string;
        off(listener: string): void;
        mount(element: HTMLElement | string): void;
        isMounted(): boolean;
        unmount(): void;
    }

    declare type QuestionElementChangeHandler: (valid: boolean) -> void;
    declare type QuestionElementErrorHandler: (error: any) -> void;

    interface QuestionOptions {
        style?: QuestionElementStyle;
    }

    // Payment
    declare class PaymentOperations {
        createCreditCardElement(options?: CreditCardOptions): CreditCardElement;
    }

    declare class CreditCardElement {
        mount(element: HTMLElement | string): void;
        unmount(): void;
        submit(): Promise;
    }

    interface CreditCardOptions {
        style?: StripeElementStyle;
    }
}

interface StripeElementStyle {
    // See https://stripe.com/docs/js/appendix/style?type=card
}

interface QuestionElementStyle {
    // Applied to all elements; all other variants inherit from these styles
    base?: {
        color?: string; // The color CSS property.
        fontFamily?: string; // The font-family CSS property.
        fontSize?: string; // The font-size CSS property.
        fontStyle?: string; // The font-style CSS property.
        fontWeight?: string; // The font-weight CSS property.
        textDecoration?: string; // The text-decoration CSS property.

        linkColor?: string; // The CSS property `color` for links.
        linkFontFamily?: string; // The font-family CSS property for links.
        linkFontSize?: string; // The font-size CSS property for links.
        linkFontStyle?: string; // The font-style CSS property for links.
        linkFontWeight?: string; // The font-weight CSS property for links.
        linkTextDecoration?: string; // The text-decoration CSS property for links.

        checkboxSize?: number; // The height and width of checkbox elements.
        checkboxBackgroundColor?: string; // The background color of unchecked checkbox elements;
        checkboxCheckedBackgroundColor?: string; // The background color of checked checkbox elements;
        checkboxColor?: string; // The color of checks in checkbox elements;

        fonts?: CssFontSource[]; // An array of font sources to load
    };
}

interface CssFontSource {
    cssSrc: string; // A relative or absolute pointing to a CSS file with @font-face definitions.
}

API Status

GET https://www.ladderlife.com/api/v2/status

This endpoint can be used to verify that the Ladder API is available and that your authorization is correct.

curl -X GET \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/status

Request parameters

None.

Response

HTTP Code	Error Type	Description
200	N/A	The Ladder API is available, and your API key is correct.
401	Unauthenticated	The caller didn't provide any credentials, or the credentials were invalid.
403	Unauthorized	The caller's credentials were valid, but don't grant permission to the requested resource.

Questions

Question object

date

{
  "id" : "InsuredPerson.DateOfBirth",
  "type" : "date",
  "caption" : "When is your birthday?",
  "subtext" : "",
  "subcaption" : "We're just calculating your age and verifying your identity",
  "supertext" : "",
  "supertext_label" : "",
  "answer" : "1980-08-13",
  "answer_valid" : true,
  "breadcrumbs" : [ ],
  "answer_options" : null,
  "uses_autocomplete_endpoint" : false
}

group

{
  "id" : "FaceAndTerm",
  "type" : "group",
  "caption" : "",
  "subtext" : "",
  "subcaption" : "",
  "supertext" : "",
  "supertext_label" : "",
  "answer_valid" : true,
  "breadcrumbs" : [ ],
  "answer_options" : null,
  "uses_autocomplete_endpoint" : false,
  "subquestions" : [ {
    "supertext_label" : "",
    "id" : "InsuredPerson.PolicyFaceAmount",
    "answer_options" : [ {
      "value" : 100000,
      "text" : "$100,000"
    }, {
      "value" : 150000,
      "text" : "$150,000"
    }, {
      "value" : 200000,
      "text" : "$200,000"
    }, "...", {
      "value" : 8000000,
      "text" : "$8,000,000"
    } ],
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "singleselect",
    "caption" : "Select coverage amount",
    "answer" : 500000,
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "id" : "DemoTerm.PolicyDuration",
    "answer_options" : [ {
      "value" : 120,
      "text" : "10 years"
    }, {
      "value" : 180,
      "text" : "15 years"
    }, {
      "value" : 240,
      "text" : "20 years"
    }, "...", {
      "value" : 360,
      "text" : "30 years"
    } ],
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "singleselect",
    "caption" : "Select term",
    "answer" : 120,
    "breadcrumbs" : [ ],
    "supertext" : ""
  } ]
}

integer

{
  "id" : "InsuredPerson.LDDRMovingViolations",
  "type" : "integer",
  "caption" : "How many moving violations or convictions have you had in the last 5 years?",
  "subtext" : "",
  "subcaption" : "Running a stop sign or red light, speeding, DUI (drugs or alcohol) — things like that",
  "supertext" : "",
  "supertext_label" : "",
  "answer" : 1,
  "answer_valid" : true,
  "breadcrumbs" : [ ],
  "answer_options" : null,
  "uses_autocomplete_endpoint" : false,
  "validation" : {
    "min" : 0
  }
}

multiselect

{
  "id" : "InsuredPerson.LDDRDangerousActivity::V2",
  "type" : "multiselect",
  "caption" : "Do you have plans to engage in any of the following activities within the next 2 years?",
  "subtext" : "",
  "subcaption" : "",
  "supertext" : "",
  "supertext_label" : "",
  "answer" : [ "NoneOfTheAbove" ],
  "answer_valid" : true,
  "breadcrumbs" : [ ],
  "answer_options" : [ {
    "value" : "SkyDiving",
    "text" : "Skydiving"
  }, {
    "value" : "ScubaDiving",
    "text" : "Scuba diving"
  }, {
    "value" : "Racing",
    "text" : "Racing"
  }, "...", {
    "value" : "NoneOfTheAbove",
    "text" : "None of these"
  } ],
  "uses_autocomplete_endpoint" : false,
  "validation" : {
    "exclusive_value" : "NoneOfTheAbove"
  }
}

multiselect

{
  "id" : "CurrentOccupation",
  "type" : "multiselect",
  "caption" : "What is your occupation?",
  "subtext" : "You can search and add multiple occupations.",
  "subcaption" : "",
  "supertext" : "",
  "supertext_label" : "",
  "answer" : [ "Therapist" ],
  "answer_valid" : true,
  "breadcrumbs" : [ "Occupation" ],
  "answer_options" : [ ],
  "uses_autocomplete_endpoint" : true,
  "answer_options_endpoint" : "https://www.ladderlife.com/api/v2/applications/app_6099ae39-23f9-4b99-9223-f6e28d0aba12/autocomplete/CurrentOccupation"
}

singleselect

{
  "id" : "TravelOutsideUS",
  "type" : "singleselect",
  "caption" : "Do you have plans to travel, live, or work outside of the U.S. within the next 2 years?",
  "subtext" : "",
  "subcaption" : "",
  "supertext" : "",
  "supertext_label" : "",
  "answer" : "No",
  "answer_valid" : true,
  "breadcrumbs" : [ ],
  "answer_options" : [ {
    "value" : "Yes",
    "text" : "yes"
  }, {
    "value" : "No",
    "text" : "no"
  } ],
  "uses_autocomplete_endpoint" : false
}

text

{
  "id" : "InsuredPerson.LDDREmail",
  "type" : "text",
  "caption" : "What is your email address?",
  "subtext" : "",
  "subcaption" : "We'll keep your email private and only use it to contact you.",
  "supertext" : "",
  "supertext_label" : "",
  "answer" : "foo@ladderlife.com",
  "answer_valid" : true,
  "breadcrumbs" : [ ],
  "answer_options" : null,
  "uses_autocomplete_endpoint" : false,
  "display_hint" : "email"
}

Field	Type	Nullable	Description
`id`	`string`		The ID of the question. We reserve the right to change question IDs at any time—you shouldn't rely on them to be stable across applications or across time.
`type`	`string`		The type of question. One of `text`, `integer`, `date`, `singleselect`, `multiselect`, `group`, `hosted`. `hosted` questions must be displayed with the Ladder JavaScript SDK.
`uses_autocomplete_endpoint`	`boolean`		For `multiselect` type questions, `true` if an autocomplete endpoint specified in `answer_options_endpoint` must be used, `false` if the answer options are passed in the `answer_options` key. Otherwise for other question types, `false`.
`display_hint`	`string`	Yes	A hint for how to show the input to the user. One of `checkbox`, `email`, `money`, `phone`, or `ssn`.
`caption`	`string`	Yes	The text displayed to the user for a question. Will be empty for `hosted` questions. To comply with applicable insurance laws and regulations, this text must be displayed to the user exactly as it is returned, without modifications, additions, or deletions.
`subtext`	`string`	Yes	The subtext of the question. To comply with applicable insurance laws and regulations, this text must be displayed to the user exactly as it is returned, without modifications, additions, or deletions.
`subcaption`	`string`	Yes	The subcaption of the question. To comply with applicable insurance laws and regulations, this text must be displayed to the user exactly as it is returned, without modifications, additions, or deletions.
`subquestions`	array of question objects	Yes	For `group` type questions, a list of subquestions to be shown to the user. Questions are nested for at most one level, so a `group` will never have a `group` as a child question.
`supertext`	`string`	Yes	Detailed text to further explain the `supertext_label`. Must be shown to the user.
`supertext_label`	`string`	Yes	The specific wording of the caption that the `supertext` refers to. See attached images for reference on how it could be shown to the user.
`compliance_documents`	array of document objects	Yes	A list of documents required to be shown to the user to comply with applicable insurance laws and regulations. Links to these documents must be shown to the user before the user answers this question.
`validation`	`object`	Yes	Validations that can be used on the client for faster user feedback. This is an object that may contain one of these fields `min` - for type `integer` questions, the minimum integer the answer can be `max` - for type `integer` questions, the maximum integer the answer can be `regex` - for type `string` questions, a regex string that the answer must match `exclusive-value` - for `multiselect` type questions, the `value` of the option that is exclusive to all other options (e.g. 'none of the above')
`breadcrumbs`	array of `string`	Yes	When asking a follow-up question, `breadcrumbs` represents the text to show for context of what sequence of conditions resulted in the follow-up. Only present on `next_incomplete_question` .
`answer`	Variable	Yes	The user-provided answer to the question, if applicable. For `text` or `number` type questions, the answer is a user-provided string or integer. For `date` type questions, the answer is the string-encoded date in `YYYY-MM-DD` form (ex. `"2021-01-05"`). For `singleselect` type questions, this field will be the `value` field of an answer option object. For `multiselect` type questions, this field will be an array of `value` fields of answer option objects. For `group` type questions, this is always `null`.
`answer_valid`	`boolean`		Whether or not the most recently provided answer was valid.
`answer_validation_message`	`string`	Yes	If `answer_valid` is false, this will be a brief description of why.
`answer_options_endpoint`	`string`	Yes	If `uses_autocomplete_endpoint` is `true`, this will be a complete URL that serves as an autocomplete endpoint. See More details on `answer_options_endpoint`.
`answer_options`	array of answer option objects	Yes	An array of objects of valid answer options. If `uses_autocomplete_endpoint` is true, this array has commonly selected answers to the question, and the autocomplete endpoint can be queried for other answers. Otherwise this is the exhaustive list of allowed answers.

Example of supertext and label

Here is an example of how we show supertext and supertext_label at ladder.

Here, the supertext_label = "tobacco or nicotine product", and the supertext is the text we see inside the popover.

In this case, you can see that the supertext_label is inside of the caption, underlined.

When the user clicks on the underlined text, we show a popover containing the supertext.

Field	Type	Nullable	Description
`query`	`string`		The query string for which to search for possible answer options. The string must be non-empty.

HTTP Code	Error Type	Description
200	N/A	Returns an array of answer options.
400	`failed_validation`	Invalid parameters were passed. Most likely, an empty query string was passed.

Questions requiring hosted fields

Some questions (demarcated with type: hosted) require using Ladder JavaScript SDK to create a hosted field.

To start, instantiate the Ladder SDK.

Next, instantiate an ApplicationOperations object by passing in the user and application IDs.

var ladderApplicationOperations = lapi.application(appId);

Next, instantiate a QuestionElement object.

var ladderQuestionElement = ladderApplicationOperations.createQuestionElement(questionId);

Next, create an empty DOM node with a unique HTML ID and pass that ID to the QuestionElement object. We'll mount a hosted field to that container:

icard.html<form id="question">
    <div id="ladder-question-element">
        <!-- Pass this div to the QuestionElement object -->
    </div>
    <button id="submit">Submit</button>
</form>

const style = {
   base: {
       color: "#123456",
   }
};

const onChange = function(valid) {
    // disable or enable the 'submit' button depending on the `valid` state
}

const onError = function(err) {
    // display an error message, e.g. asking the user to refresh & try again
}

const question = ladderApplicationOperations.createQuestionElement(questionId, { style: style });
question.on('change', onChange);
question.on('error', onError);
question.mount("#ladder-question-element");

The QuestionElement object will collect all necessary answers from the user and send them directly to Ladder's servers. Upon user input, the QuestionElement will fire the supplied change event and call any registered handlers with a boolean indicating whether the user input is valid or not.

When the user's input is invalid, you should not allow the user to proceed by disabling your form. After the user's input is valid, you should re-enable your form.

To proceed, answer the question via the API, with true as the value.

Applications

Application object

{
  "id" : "app_6099ae39-23f9-4b99-9223-f6e28d0aba12",
  "hash" : "0bfb9d24-6780-5494-b0de-619ea68027e4",
  "face_amount" : 500000,
  "duration_years" : 10,
  "user" : "user_ea4fb555-42d4-4545-a4d6-3f4d0e51e264",
  "eligible_for_api" : true,
  "ineligible" : false,
  "created_at" : 1577836834,
  "next_incomplete_question" : {
    "id" : "DemoTerm.LDDRAddressGroup",
    "type" : "group",
    "caption" : "What is your address?",
    "subtext" : "",
    "subcaption" : "This info helps us verify your identity so that we can make you a personalized offer. We'll keep it private.",
    "supertext" : "",
    "supertext_label" : "",
    "answer_valid" : false,
    "breadcrumbs" : [ "What is your address?" ],
    "answer_options" : null,
    "uses_autocomplete_endpoint" : false,
    "subquestions" : [ {
      "id" : "InsuredPerson.Street",
      "type" : "text",
      "caption" : "Residential street address",
      "subtext" : "PO boxes aren't permitted",
      "subcaption" : "",
      "supertext" : "",
      "supertext_label" : "",
      "answer_valid" : false,
      "breadcrumbs" : [ ],
      "answer_options" : null,
      "uses_autocomplete_endpoint" : false
    }, {
      "id" : "InsuredPerson.Street2",
      "type" : "text",
      "caption" : "Street address line 2",
      "subtext" : "",
      "subcaption" : "",
      "supertext" : "",
      "supertext_label" : "",
      "answer_valid" : true,
      "breadcrumbs" : [ ],
      "answer_options" : null,
      "uses_autocomplete_endpoint" : false
    }, {
      "id" : "InsuredPerson.City",
      "type" : "text",
      "caption" : "City",
      "subtext" : "",
      "subcaption" : "",
      "supertext" : "",
      "supertext_label" : "",
      "answer_valid" : false,
      "breadcrumbs" : [ ],
      "answer_options" : null,
      "uses_autocomplete_endpoint" : false
    }, {
      "id" : "InsuredPerson.ResidenceState",
      "type" : "singleselect",
      "caption" : "State",
      "subtext" : "",
      "subcaption" : "",
      "supertext" : "",
      "supertext_label" : "",
      "answer" : "CaliforniaCA",
      "answer_valid" : true,
      "breadcrumbs" : [ ],
      "answer_options" : [ {
        "value" : "AlabamaAL",
        "text" : "Alabama (AL)"
      }, {
        "value" : "AlaskaAK",
        "text" : "Alaska (AK)"
      }, {
        "value" : "ArizonaAZ",
        "text" : "Arizona (AZ)"
      }, "...", {
        "value" : "WyomingWY",
        "text" : "Wyoming (WY)"
      } ],
      "uses_autocomplete_endpoint" : false
    }, {
      "id" : "InsuredPerson.ZipCode",
      "type" : "text",
      "caption" : "Zip code",
      "subtext" : "",
      "subcaption" : "",
      "supertext" : "",
      "supertext_label" : "",
      "answer" : "94025",
      "answer_valid" : true,
      "breadcrumbs" : [ ],
      "answer_options" : null,
      "uses_autocomplete_endpoint" : false
    } ]
  },
  "answered_questions" : [ {
    "supertext_label" : "",
    "id" : "InsuredPerson.Gender",
    "answer_options" : [ {
      "value" : "Male",
      "text" : "Male"
    }, {
      "value" : "Female",
      "text" : "Female"
    } ],
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "singleselect",
    "caption" : "What is your sex?",
    "answer" : "Female",
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "validation" : {
      "min" : 0
    },
    "id" : "InsuredPerson.Height",
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "integer",
    "caption" : "How tall are you?",
    "answer" : 72,
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "validation" : {
      "min" : 0
    },
    "id" : "InsuredPerson.Weight",
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "integer",
    "caption" : "What is your current weight?",
    "answer" : 175,
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "id" : "InsuredPerson.DateOfBirth",
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "We're just calculating your age and verifying your identity",
    "type" : "date",
    "caption" : "When is your birthday?",
    "answer" : "1980-08-13",
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "id" : "InsuredPerson.LDDREmail",
    "subtext" : "",
    "display_hint" : "email",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "We'll keep your email private and only use it to contact you.",
    "type" : "text",
    "caption" : "What is your email address?",
    "answer" : "foo@ladderlife.com",
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "id" : "FaceAndTerm",
    "subtext" : "",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "group",
    "subquestions" : [ {
      "supertext_label" : "",
      "id" : "InsuredPerson.PolicyFaceAmount",
      "answer_options" : [ {
        "value" : 100000,
        "text" : "$100,000"
      }, {
        "value" : 150000,
        "text" : "$150,000"
      }, {
        "value" : 200000,
        "text" : "$200,000"
      }, {
        "value" : 250000,
        "text" : "$250,000"
      }, {
        "value" : 300000,
        "text" : "$300,000"
      }, {
        "value" : 350000,
        "text" : "$350,000"
      }, {
        "value" : 400000,
        "text" : "$400,000"
      }, {
        "value" : 450000,
        "text" : "$450,000"
      }, {
        "value" : 500000,
        "text" : "$500,000"
      }, {
        "value" : 550000,
        "text" : "$550,000"
      }, {
        "value" : 600000,
        "text" : "$600,000"
      }, {
        "value" : 650000,
        "text" : "$650,000"
      }, {
        "value" : 700000,
        "text" : "$700,000"
      }, {
        "value" : 750000,
        "text" : "$750,000"
      }, {
        "value" : 800000,
        "text" : "$800,000"
      }, {
        "value" : 850000,
        "text" : "$850,000"
      }, {
        "value" : 900000,
        "text" : "$900,000"
      }, {
        "value" : 950000,
        "text" : "$950,000"
      }, {
        "value" : 1000000,
        "text" : "$1,000,000"
      }, {
        "value" : 1100000,
        "text" : "$1,100,000"
      }, {
        "value" : 1200000,
        "text" : "$1,200,000"
      }, {
        "value" : 1300000,
        "text" : "$1,300,000"
      }, {
        "value" : 1400000,
        "text" : "$1,400,000"
      }, {
        "value" : 1500000,
        "text" : "$1,500,000"
      }, {
        "value" : 1600000,
        "text" : "$1,600,000"
      }, {
        "value" : 1700000,
        "text" : "$1,700,000"
      }, {
        "value" : 1800000,
        "text" : "$1,800,000"
      }, {
        "value" : 1900000,
        "text" : "$1,900,000"
      }, {
        "value" : 2000000,
        "text" : "$2,000,000"
      }, {
        "value" : 2250000,
        "text" : "$2,250,000"
      }, {
        "value" : 2500000,
        "text" : "$2,500,000"
      }, {
        "value" : 2750000,
        "text" : "$2,750,000"
      }, {
        "value" : 3000000,
        "text" : "$3,000,000"
      }, {
        "value" : 3250000,
        "text" : "$3,250,000"
      }, {
        "value" : 3500000,
        "text" : "$3,500,000"
      }, {
        "value" : 3750000,
        "text" : "$3,750,000"
      }, {
        "value" : 4000000,
        "text" : "$4,000,000"
      }, {
        "value" : 4250000,
        "text" : "$4,250,000"
      }, {
        "value" : 4500000,
        "text" : "$4,500,000"
      }, {
        "value" : 4750000,
        "text" : "$4,750,000"
      }, {
        "value" : 5000000,
        "text" : "$5,000,000"
      }, {
        "value" : 5500000,
        "text" : "$5,500,000"
      }, {
        "value" : 6000000,
        "text" : "$6,000,000"
      }, {
        "value" : 6500000,
        "text" : "$6,500,000"
      }, {
        "value" : 7000000,
        "text" : "$7,000,000"
      }, {
        "value" : 7500000,
        "text" : "$7,500,000"
      }, {
        "value" : 8000000,
        "text" : "$8,000,000"
      } ],
      "subtext" : "",
      "uses_autocomplete_endpoint" : false,
      "answer_valid" : true,
      "subcaption" : "",
      "type" : "singleselect",
      "caption" : "Select coverage amount",
      "answer" : 500000,
      "breadcrumbs" : [ ],
      "supertext" : ""
    }, {
      "supertext_label" : "",
      "id" : "DemoTerm.PolicyDuration",
      "answer_options" : [ {
        "value" : 120,
        "text" : "10 years"
      }, {
        "value" : 180,
        "text" : "15 years"
      }, {
        "value" : 240,
        "text" : "20 years"
      }, {
        "value" : 300,
        "text" : "25 years"
      }, {
        "value" : 360,
        "text" : "30 years"
      } ],
      "subtext" : "",
      "uses_autocomplete_endpoint" : false,
      "answer_valid" : true,
      "subcaption" : "",
      "type" : "singleselect",
      "caption" : "Select term",
      "answer" : 120,
      "breadcrumbs" : [ ],
      "supertext" : ""
    } ],
    "caption" : "",
    "breadcrumbs" : [ ],
    "supertext" : ""
  }, {
    "supertext_label" : "",
    "id" : "InsuredPerson.SocialSecurityNumber",
    "subtext" : "",
    "display_hint" : "ssn",
    "uses_autocomplete_endpoint" : false,
    "answer_valid" : true,
    "subcaption" : "",
    "type" : "text",
    "caption" : "What is your social security number?",
    "breadcrumbs" : [ ],
    "supertext" : ""
  } ],
  "estimated_progress" : 0.17073171
}

Field	Type	Nullable	Description
`id`	`string`		The ID of the application.
`hash`	`string`		A hash of the application, used for signing the application. See Sign the application. The hash changes when the application is modified.
`user`	`string`		The `id` of the user associated with the application. See the user object.
`offer`	`string`	Yes	The `id` of the latest offer, if one exists. See the offer object.
`policy`	`string`	Yes	The `id` of the current policy, if one exists. See the policy object.
`created_at`	`integer`		The timestamp of when the application was started; in seconds since Unix epoch.
`signed_at`	`integer`	Yes	The timestamp of when the application was signed; in seconds since Unix epoch.
`closed_at`	`integer`	Yes	The timestamp at which the application was closed, and so cannot be signed and further questions cannot be answered; in seconds since Unix epoch.
`duration_years`	`integer`	Yes	The duration of the policy being applied for, in years.
`eligible_for_api`	`boolean`		Applications in certain states must be redirected to the Ladder site to comply with applicable laws and regulations. Those applications will have `eligible_for_api = false` . If the user would like to proceed, use a Ladder redirect link to continue.
`face_amount`	`integer`	Yes	The face amount of the policy being applied for; in US dollars.
`ineligible`	`boolean`		Whether or not the application is currently ineligible for a decision, based on prior answers.
`ineligibility_reason`	`string`	Yes	Reason why the application is currently ineligible for a decision, based on prior answers.
`identity_status`	`string`	Yes	The status of ID verification for the applicant. Can be `verified`, `invalid`, `pending`, `duplicate`, or `different`.
`next_incomplete_question`	question object	Yes	The next unanswered question in the application.
`answered_questions`	array of question objects		Answered questions in the application, ordered by when they were first answered, in ascending order.
`estimated_progress`	`float`		An estimate of how close this application is to being completed, returned as a number between 0 and 1. Useful for implementing a progress bar.

Start an application

POST https://www.ladderlife.com/api/v2/applications

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/applications \
	-d '{
  "email" : "foo@ladderlife.com",
  "quoter" : "ea4fb555-42d4-4545-a4d6-3f4d0e51e264"
}'

Request parameters

Field	Type	Optional	Description
`user`	`string`	Yes	The ID of the user. One of `user` and `quoter` must be provided.
`quoter`	`string`	Yes	The ID returned by the quoter API. Used for linking the quote with the application. One of `user` and `quoter` must be provided.
`email`	`string`	Yes	The user's email. Helps prevent duplicate applications if the user already signed an app on Ladder's platform.
`state`	`string`	Yes	The user's residence state, in two-letter abbreviated form. Useful for determining ahead of time what application version is required. Ex. `CA`

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200		Returns an application object.
302		Users in New York should be redirected to the Ladder site to comply with applicable insurance laws and regulations. Please redirect them using the url provided in the `Location` header.
400	`failed_validation`	See the `details` dictionary for more details. Most likely, the quoter/user ID, email, or state is missing or invalid.
400	`has_open_app`	The user already has an open application.
403	`not_allowed`	The user is not allowed to open a new application.
409	`email_taken`	The user has an existing Ladder account. They should proceed by visiting the Ladder site directly to continue their application.

Get an application

GET https://www.ladderlife.com/api/v2/applications/:id

curl -X GET \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/applications/app_ea4fb555-42d4-4545-a4d6-3f4d0e51e264

Request parameters

None.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200		Returns an application object.

Answer a question

POST https://www.ladderlife.com/api/v2/applications/:id/answer

Answer a group

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/applications/app_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/answer \
	-d '{
  "id" : "DemoTerm.LDDRAddressGroup",
  "value" : {
    "InsuredPerson.Street" : "650 Live Oak Ave",
    "InsuredPerson.Street2" : "Hello",
    "InsuredPerson.City" : "Menlo Park",
    "InsuredPerson.ResidenceState" : "CaliforniaCA",
    "InsuredPerson.ZipCode" : "94025"
  }
}'

Answer a multiselect

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/applications/app_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/answer \
	-d '{
  "id" : "InsuredPerson.LDDRDangerousActivity::V2",
  "value" : [ "NoneOfTheAbove" ]
}'

Answer a singleselect

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/applications/app_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/answer \
	-d '{
  "id" : "TravelOutsideUS",
  "value" : "No"
}'

Request parameters

Field	Type	Optional	Description
`id`	`string`		The ID of the question
`value`	Variable		For `text` or `integer` type questions, this is the user-provided text or integer. For `date` type questions, this is the string-encoded date in `YYYY-MM-DD` form (ex. `2021-01-05`). For `singleselect` type questions, this is the `value` of the answer option For `multiselect` type, this is an array of the `value` of the answer option For `group` type questions, this is a map where the keys are the ID of the subquestion, and the values are the above, depending on the type of the subquestion. For `hosted` type questions, this should be the boolean value `true`.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	On success, returns an application object.
400	`failed_validation`	The user's answer failed validation.
400	`application_already_signed`	The application has already been signed, and is therefore locked from more answers.
400	`application_closed`	The application is closed.

Sign the application

POST https://www.ladderlife.com/api/v2/applications/:id/sign

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/applications/app_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/sign \
	-d '{
  "hash" : "24412bf1-6496-5ba7-8d8a-d118223b9064"
}'

Once an application is signed, users can no longer change their questionnaire answers. At this point, the application is considered "signed" and and an insurance offer decision will be made.

Request parameters

Field	Type	Optional	Description
`hash`	`string`		The hash of the application being signed. See the `hash` field in the application object.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	On success, returns an application object.
302		Due to their answers, this user should be redirected to the Ladder site to comply with applicable insurance laws and regulations. Please redirect them using the url provided in the `Location` header.
400	`ineligible`	Due to their answers, the user is ineligible for life insurance. See the `details` dictionary for more details.
400	`no_authorizations`	The authorizations were not accepted.
400	`application_incomplete`	Not all the questions were answered, but a finalization was attempted.
400	`application_closed`	The application is closed.
400	`hash_mismatch`	The current hash of the application did not match the given hash in the request.

Retrieve the decision for the application

GET https://www.ladderlife.com/api/v2/applications/:id/decision

curl -X GET \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/applications/app_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/decision

This endpoint can be called once the app is signed. It can be polled for continual updates on the decision status.

A decision is guaranteed to take less than two minutes.

Request parameters

None.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	On success, returns an object with the fields specified below.
400	`application_not_signed`	The application is not signed.

{
  "status" : "pending",
  "decision" : null
}

{
  "status" : "completed",
  "decision" : "term",
  "offer" : "offer_c5149818-561a-4c45-a201-a2575f7bd915"
}

{
  "status" : "completed",
  "decision" : "manual_underwriting"
}

Field	Type	Nullable	Description
`status`	`string`		The status of the decision. Will either be `pending` or `completed`.
`decision`	`string`	Yes	The decision made. Will either be `term`, `manual_underwriting`, or `declined`.
`offer`	`string`	Yes	If the `decision` was `term`, the `id` of the offer linked to the decision.

Get all documents for an application

GET https://www.ladderlife.com/api/v2/applications/:id/documents

curl -X GET \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/applications/null/documents

Request Parameters

None

Response

Returns an array of document objects associated with the application. This will include user-level and policy-level documents, if any exist.

Payment

To avoid the direct handling of sensitive cardholder data, please use Ladder's Javascript SDK. This SDK creates a hosted field such that the cardholder sends all sensitive card data directly to Ladder's payment provider's PCI DSS-validated servers.

Note that Ladder's payment service provider keeps user payment information on file. Once validated, it is not necessary to collect payment information from the user again, even if they log out of the application and return at a later date. You can check the status of user payment information using the payment_status field of the user object

Collecting payment information

To start, instantiate the Ladder SDK.

When you're ready to accept payment for an application, instantiate a PaymentOperations object by passing in the user ID associated with the application:

const ladderPaymentOperations = ladderApi.payment();

Next, create an empty DOM node with a unique ID in your payment form and pass that ID to the PaymentOperations object. We'll mount a hosted field to that container:

icard.html<form id="payment">
    <div id="ladder-card-element">
        <!-- Pass this div to the PaymentOperations object -->
    </div>
    <button id="submit">Authorize payment</button>
</form>

const style = {
   base: {
       color: "#123456",
   }
};
const card = ladderPaymentOperations.createCreditCardElement({ style: style });
card.mount("#ladder-card-element");

The CreditCardElement object will collect all necessary card and billing details, including card number, expiration, CVC, and zipcode.

To submit payment to Ladder, bind the form's submit action to card.submit():

const form = document.getElementById("payment");
form.addEventListener("submit", e => {
   e.preventDefault();
   card.submit().then(() => {
       // Show a success message to the customer
   }).catch(err => {
       // Show the error to the customer
   });
});

card.submit() may take a few seconds to complete. You should disable your form from being edited or resubmitted during that time.

To preload some of the data required for accepting payment, you may call ladderApi.payment() without any other calls. This may result in a faster time-to-mount later.

Updating payment information

Updating payment information can be done in the exact same manner as collecting payment.

Offers

Offer object

Open offer

{
  "id" : "offer_c5149818-561a-4c45-a201-a2575f7bd915",
  "hash" : "3b3f40bc-abfd-577c-a8d1-5e1d1528e368",
  "status" : "active",
  "face_amount" : 500000,
  "monthly_premium_cents" : 1407,
  "duration_years" : 10,
  "application" : "app_6099ae39-23f9-4b99-9223-f6e28d0aba12",
  "expires_at" : 1579132936,
  "offered_at" : 1577836936
}

Accepted offer

{
  "id" : "offer_c5149818-561a-4c45-a201-a2575f7bd915",
  "hash" : "3b3f40bc-abfd-577c-a8d1-5e1d1528e368",
  "status" : "accepted",
  "face_amount" : 500000,
  "monthly_premium_cents" : 1407,
  "duration_years" : 10,
  "application" : "app_6099ae39-23f9-4b99-9223-f6e28d0aba12",
  "policy" : "TL-146-1180-1B39F500T10X1",
  "expires_at" : 1579132936,
  "offered_at" : 1577836936
}

Field	Type	Nullable	Description
`id`	`string`		A unique identifier for the offer
`application`	`string`		The `id` of the application for which this offer is for
`policy`	`string`	Yes	The `id` of the policy for which this offer led to
`status`	`string`		The status of the offer. Can be `active`, `accepted`, `refused`, `expired`, or `canceled`.
`offered_at`	`integer`		The timestamp at which the offer was given; in seconds since Unix epoch.
`expires_at`	`integer`		The timestamp at which the offer will expire; in seconds since Unix epoch.
`face_amount`	`integer`		The face amount of the policy if the offer is accepted, in US dollars.
`duration_years`	`integer`		The duration of the policy if the offer is accepted, in years.
`monthly_premium_cents`	`integer`		The monthly premium of the policy if the offer is accepted, in US cents.
`poca_amendment`	poca amendment object	Yes	[BETA] An optional post offer coverage amendment (POCA) should the user decide to amend their offer
`hash`	`string`	Yes	[BETA] The computed hash of the offer, required to accept an offer with an amendment

POCA amendment object

Post offer coverage amendment (POCA) offer

{
  "id" : "offer_c5149818-561a-4c45-a201-a2575f7bd915",
  "hash" : "1ac9e752-3ce4-54f3-aa9a-c960e25f5b0b",
  "status" : "active",
  "face_amount" : 500000,
  "monthly_premium_cents" : 1407,
  "duration_years" : 10,
  "poca_amendment" : {
    "amendment_text" : "I, Edmond Halley, amend my LadderLife™ Application as follows:\nI would like to replace the Coverage Amount I originally applied for with a Coverage Amount equal to $100k.\nI understand that this amendment will become a part of the LadderLife™ Application I signed on 12-31-2019. Since that date, my health has not changed, and I have not had any application for life insurance postponed or declined, or been offered insurance with substandard risk pricing.",
    "face_amount" : 100000,
    "duration_years" : 10,
    "monthly_premium_cents" : 925
  },
  "application" : "app_6099ae39-23f9-4b99-9223-f6e28d0aba12",
  "expires_at" : 1579132936,
  "offered_at" : 1577836936
}

Field	Type	Description
`amendment_text`	`string`	The text representing the legal amendment to the application, required to be shown to the user
`face_amount`	`integer`	The face amount of the policy if the offer is accepted, in US Dollars.
`duration_years`	`integer`	The duration of the policy if the offer is accepted, in years.
`monthly_premium_cents`	`integer`	The monthly premium of the policy if the offer is accepted, in US cents.

POCA Quotes object

POCA quotes

{
  "quotes" : [ {
    "term" : 10,
    "coverage" : 100000,
    "daily_price" : 0.3,
    "monthly_premium" : 9.25
  }, {
    "term" : 15,
    "coverage" : 100000,
    "daily_price" : 0.28,
    "monthly_premium" : 8.53
  }, {
    "term" : 20,
    "coverage" : 100000,
    "daily_price" : 0.3,
    "monthly_premium" : 9.27
  }, {
    "term" : 25,
    "coverage" : 100000,
    "daily_price" : 0.42,
    "monthly_premium" : 12.8
  }, {
    "term" : 30,
    "coverage" : 100000,
    "daily_price" : 0.44,
    "monthly_premium" : 13.6
  }, {
    "term" : 10,
    "coverage" : 150000,
    "daily_price" : 0.34,
    "monthly_premium" : 10.36
  }, {
    "term" : 15,
    "coverage" : 150000,
    "daily_price" : 0.32,
    "monthly_premium" : 9.97
  }, {
    "term" : 20,
    "coverage" : 150000,
    "daily_price" : 0.36,
    "monthly_premium" : 11.17
  }, {
    "term" : 25,
    "coverage" : 150000,
    "daily_price" : 0.49,
    "monthly_premium" : 14.97
  }, {
    "term" : 30,
    "coverage" : 150000,
    "daily_price" : 0.54,
    "monthly_premium" : 16.67
  } ],
  "available_coverages" : [ 100000, 150000, 200000, 250000, 300000, 350000, 400000, 450000, 500000 ],
  "available_terms" : [ 10, 15, 20, 25, 30 ]
}

Field	Type	Nullable	Description
`quotes`	array of quote objects	No	All the available quotes for the possible term + coverage combinations.
`available_terms`	array of `integer`	No	Array of terms available to change to.
`available_coverages`	array of `integer`	No	Array of coverages available to change to.

POCA Quote object

POCA quotes

{
  "coverage" : 100000,
  "term" : 10,
  "monthly_premium" : 9.25,
  "daily_price" : 0.3
}

Field	Type	Description
`coverage`	`integer`	Face coverage amount, in US Dollars.
`term`	`integer`	Term length, in years.
`monthly_premium`	`float`	The premium for the proposed policy conditions.
`daily_price`	`float`

Get an offer

GET https://www.ladderlife.com/api/v2/offers/:id

curl -X GET \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/offers/offer_ea4fb555-42d4-4545-a4d6-3f4d0e51e264

Request parameters

None.

Response

HTTP Code	Error Type	Description
200	N/A	Returns an offer object.

Amend an offer

To make a 'Post offer coverage amendment' (POCA), you first will need to determine the term length and face amount the user would like.

First, you can get a list of all quotes for the available coverage/term options, these can be displayed to the user so they can make a decision.

Get list of POCA quotes

GET https://www.ladderlife.com/api/v2/offers/:id/poca-quotes

curl -X GET \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/offers/offer_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/poca-quotes

Request Parameters

None.

Response

HTTP Code	Error Type	Description
200	N/A	Returns an poca quotes object.

Patch the current offer

Once the user has selected a new coverage amount and/or term, patch the offer with the new values.

PATCH https://www.ladderlife.com/api/v2/offers/:id

curl -X PATCH \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/offers/offer_ea4fb555-42d4-4545-a4d6-3f4d0e51e264 \
	-d '{
  "coverage" : 100000,
  "term" : 10
}'

Request Parameters

Field	Type	Required	Description
`coverage`	`integer`	`true`	The new coverage amount to amend to the offer, cannot be greater than the one the user applied for.
`term`	`term`	`true`	The new term length, in years.

Response

HTTP Code	Error Type	Description
200	N/A	Returns an poca amendment object.
400	`max_allowed_coverage_exceeded`	Coverage greater than max amount of coverage
400	`max_allowed_term_exceeded`	Term greater than max term length
400	`coverage_amount_not_available`	Coverage amount is not allowed
400	`term_length_not_available`	Term length is not allowed

Displaying the POCA

Inside of the poca amendment object you will find an amendment_text string.

Example from the ladderlife.com website.

Reverting the POCA.

The original term/coverage amounts will still be on the offer object under the default `

Although you must show the amended amounts when the user accepts an offer, they will still be present if you wish to revert.

If the user wishes to revert their change, simply call the PATCH offer endpoint again with the original coverage/term.

Then you may accept an offer as normal.

Accept an offer

POST https://www.ladderlife.com/api/v2/offers/:id/accept

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/offers/offer_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/accept

Before accepting an offer, a payment method must be set on the user/application. See the Payment section for details.

Request parameters

Field	Type	Required	Description
`hash`	`string`	`false`	The hash of the offer object, only required if the user is making a POCA.

Response

HTTP Code	Error Type	Description
200	N/A	Returns an offer object.
410	`offer_expired`	The offer is expired.
409	`offer_inactive`	The offer is inactive and cannot be accepted or refused.
402	`no_payment`	No payment method was set for the user.
400	`payment_failed`	The payment failed when attempting to charge the user.
400	`invalid_hash`	Incorrect hash provided. Only applied to POCA offers.

Refuse an offer

POST https://www.ladderlife.com/api/v2/offers/:id/refuse

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/offers/offer_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/refuse

Request parameters

None.

Response

HTTP Code	Error Type	Description
200	N/A	Returns an offer object.
410	`offer_expired`	The offer is expired.
409	`offer_inactive`	The offer has already been accepted or refused.

Policies

Policy object

{
  "id" : "TL-146-1180-1B39F500T10X1",
  "status" : "active",
  "face_amount" : 500000,
  "monthly_premium_cents" : 1407,
  "duration_years" : 10,
  "application" : "app_6099ae39-23f9-4b99-9223-f6e28d0aba12",
  "beneficiaries_editable" : true,
  "beneficiaries" : [ {
    "email" : "jchen@ladderlife.com",
    "relationship" : "husband",
    "address" : {
      "street_line_1" : "123 Main St",
      "city" : "San Francisco",
      "state" : "CA",
      "zipcode" : "94107"
    },
    "social_security_number" : "123-45-6789",
    "last_name" : "Chen",
    "first_name" : "Jeff",
    "date_of_birth" : "1989-08-28",
    "type" : "person",
    "phone" : "(321) 456-7890",
    "share" : 100
  } ],
  "contingent_beneficiaries" : [ {
    "email" : "jack@ladderlife.com",
    "relationship" : "husband",
    "address" : {
      "street_line_1" : "321 Main St",
      "city" : "Menlo Park",
      "state" : "CA",
      "zipcode" : "94025"
    },
    "social_security_number" : "321-45-6789",
    "last_name" : "Dubie",
    "first_name" : "Jack",
    "date_of_birth" : "1988-11-20",
    "type" : "person",
    "phone" : "(321) 456-7890",
    "share" : 100
  } ],
  "issued_at" : 1577837089
}

Field	Type	Nullable	Description
`id`	`string`		A unique identifier for the policy
`application`	`string`		The `id` of the application for which this policy was from
`status`	`string`		The status of the policy. Can be `active`, `canceled`, or `lapsed`.
`issued_at`	`integer`		The timestamp at which the policy was issued; in seconds since Unix epoch.
`canceled_at`	`integer`	Yes	The timestamp at which the policy was canceled; in seconds since Unix epoch.
`face_amount`	`integer`		The face amount of the policy if the offer is accepted; in US dollars.
`duration_years`	`integer`		The duration of the policy if the offer is accepted; in years.
`monthly_premium_cents`	`integer`		The monthly premium of the policy if the offer is accepted; in US cents.
`beneficiaries`	array of beneficiary objects		The current (primary) beneficiaries of this policy.
`contingent_beneficiaries`	array of beneficiary objects		The current contingent beneficiaries of this policy.
`beneficiaries_editable`	`boolean`		Whether the beneficiaries can be changed.

Get a policy

GET https://www.ladderlife.com/api/v2/policies/:id

Request parameters

None.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	Returns a policy object.
403	`not_viewable`	The API user does not have permission to view this policy's details (e.g. not appointed in all states)

Update a policy

PATCH https://www.ladderlife.com/api/v2/policies/:id

curl -X PATCH \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/policies/TL-146-1180-1B39F500T10X1 \
	-d '{
  "beneficiaries" : [ {
    "email" : "jchen@ladderlife.com",
    "relationship" : "husband",
    "address" : {
      "street_line_1" : "123 Main St",
      "city" : "San Francisco",
      "state" : "CA",
      "zipcode" : "94107"
    },
    "social_security_number" : "123-45-6789",
    "last_name" : "Chen",
    "first_name" : "Jeff",
    "date_of_birth" : "1989-08-28",
    "type" : "person",
    "phone" : "(321) 456-7890",
    "share" : 100
  } ]
}'

Request Parameters

Field	Type	Optional	Description
`beneficiaries`	array of beneficiary objects	Yes	The new beneficiaries for the policy. Note that this endpoint replaces the full set of beneficiaries for the policy.
`contingent_beneficiaries`	array of beneficiary objects	Yes	The new contingent beneficiaries for the policy. Note that this endpoint replaces the full set of contingent beneficiaries for the policy.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	On success, returns a policy object.
403	`not_viewable`	The API user does not have permission to view this policy's details (e.g. not appointed in all states)
400	`failed_validation`	One or more of the fields do not match the expected format (the error will have more details)
400	`beneficiaries_bad_sum`	The (primary OR contingent) beneficiary shares do not add up to 100%.
400	`duplicate_beneficiaries`	The same beneficiary appears more than once globally.
400	`no_primary_beneficiary`	Attempting to set contingent beneficiaries without setting any primary beneficiaries.
400	`beneficiaries_immutable`	The beneficiaries of this policy cannot be changed (in cases of e.g. collateral assignment)

Users

User object

User filling out an application

{
  "id" : "user_ea4fb555-42d4-4545-a4d6-3f4d0e51e264",
  "current_application" : "app_6099ae39-23f9-4b99-9223-f6e28d0aba12",
  "applications" : [ "app_6099ae39-23f9-4b99-9223-f6e28d0aba12" ],
  "policies" : [ ],
  "name" : {
    "first_name" : "Edmond",
    "middle_name" : "Flamsteed",
    "last_name" : "Halley"
  },
  "allowed_to_start_app" : false,
  "payment_status" : "not_submitted",
  "phone" : "(321) 456-7890"
}

User who has completed their application, has a policy, and address

{
  "id" : "user_ea4fb555-42d4-4545-a4d6-3f4d0e51e264",
  "applications" : [ "app_6099ae39-23f9-4b99-9223-f6e28d0aba12" ],
  "policies" : [ "TL-146-1180-1B39F500T10X1" ],
  "name" : {
    "first_name" : "Edmond",
    "middle_name" : "Flamsteed",
    "last_name" : "Halley"
  },
  "address" : {
    "street_line_1" : "555 University Ave",
    "city" : "Palo Alto",
    "state" : "CA",
    "zipcode" : "94568"
  },
  "allowed_to_start_app" : true,
  "payment_status" : "submitted",
  "phone" : "(321) 456-7890"
}

Fields

Field	Type	Nullable	Description
`id`	`string`		The ID of the user
`name`	name object	Yes	The name of the user
`address`	address object	Yes	The address of the user
`phone`	`string`	Yes	The phone number of the user
`current_application`	`string`	Yes	The ID of the user's current, in-progress application, if any exists.
`applications`	array of `string`		An array of IDs of applications the user has started
`policies`	array of `string`		An array of IDs of policies issued to the user
`allowed_to_start_app`	`boolean`		Whether the user is allowed to start a new application. If not, calls to `POST /applications` will not succeed.

| payment_status | string | | Status of the user's payment information. Can be one of:

          `submitted` - ladder's payment service provider has received the user's payment info
          `not_submitted` - ladder's payment service provider has not received the user's payment info |

Get a public token

POST https://www.ladderlife.com/api/v2/users/:id/token

This endpoint is used to create a token for the initialization of the Payment SDK.

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/users/user_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/token

Request Parameters

None.

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	On success, returns an object with the fields specified below.

{
  "token" : "ezpiYXNlLXVybCAiaHR0cDovL2xvY2FsaG9zdDozMDAwIiwgOnRva2VuICJ3X1J3TXpVRzNUV3QxbkYxeE5pZ3pnIn0"
}

Field	Type	Nullable	Description
`token`	`string`		The token string

Retrieve a Ladder redirect link

POST https://www.ladderlife.com/api/v2/users/:id/redirect

curl -X POST \
	-H "Authorization: Bearer your-api-key" \
	https://www.ladderlife.com/api/v2/users/user_ea4fb555-42d4-4545-a4d6-3f4d0e51e264/redirect

Returns a link that the user can be redirected to, which will bring them to the Ladder site.

Request parameters

None

Response

HTTP Code	Error Type	Description
200	N/A	On success, returns an object with the fields specified below.

{
  "link" : "https://www.ladderlife.com/api/v1/redirect/ea4fb555-42d4-4545-a4d6-3f4d0e51e264?token=e4O9RVEjhIFIzEga0agZqg",
  "expires_at" : 1577840825
}

Field	Type	Nullable	Description
`link`	`string`		An auth link which will bring the user to the Ladder site, logged in. Auth links are one-time-use and should be treated like secrets.

Update a user

PATCH https://www.ladderlife.com/api/v2/users/:id

curl -X PATCH \
	-H "Authorization: Bearer your-api-key" \
	-H "Content-Type: application/json" \
	https://www.ladderlife.com/api/v2/users/user_ea4fb555-42d4-4545-a4d6-3f4d0e51e264 \
	-d '{
  "address" : {
    "street_line_1" : "555 University Ave",
    "city" : "Palo Alto",
    "state" : "CA",
    "zipcode" : "94568"
  }
}'

Request params

Field	Type	Optional	Description
`address`	address object		The address of the user

Response

This endpoint may return the following responses:

HTTP Code	Error Type	Description
200	N/A	Returns a user object.
400	`failed_validation`	Invalid parameters were passed.

Appendix

These resources are included inside other resources, and so do not have their own endpoints.

Answer option object

{
  "text" : "Iowa (IA)",
  "value" : "IowaIA"
}

{
  "text" : "20 years",
  "value" : 240
}

{
  "text" : "Vermont (VT)",
  "value" : "VermontVT"
}

{
  "text" : "Yes",
  "value" : "Yes"
}

{
  "text" : "$1,000,000",
  "value" : 1000000
}

Field	Type	Nullable	Description
`value`	Variable		The value of the option.
`text`	`string`		The text displayed to the user for an option.
`hint`	`string`	Yes	Extra description of the option, must be shown to the user.
`details`	`string`	Yes	A brief, more in-depth description of the option. Can be displayed to the user.

Example on how hints can be shown

Here is a way you could shows hints on answer options.

Here we include an info button that shows a popover when clicked on each potential answer with the hint.

Address object

{
  "street_line_1" : "123 Main St",
  "city" : "San Francisco",
  "state" : "CA",
  "zipcode" : "94107"
}

Field	Type	Nullable	Description
`street_line_1`	`string`		The first address line component of the address.
`street_line_2`	`string`	Yes	The second address line component of the address.
`city`	`string`		The city component of the address.
`state`	`string`		The state component of the address, in two-letter abbreviated form.
`zipcode`	`string`		The zipcode component of the address.

Name object

{
  "first_name" : "Edmond",
  "last_name" : "Halley",
  "middle_name" : "Flamsteed"
}

Field	Type	Nullable	Description
`first_name`	`string`		The first name of the entity.
`middle_name`	`string`	Yes	The middle name of the entity.
`last_name`	`string`		The last name of the entity.

Document object

{
  "name" : "Insurance policy",
  "link" : "https://www.ladderlife.com/api/v2/docs/fb5f21e4-1e61-4ba3-b7f2-5352241d050c"
}

Field	Type	Nullable	Description
`name`	`string`		The name of the document, to display to the user.
`link`	`string`		A pre-authenticated URL to the document. This URL is valid for up to 60 minutes. At the moment, all documents are PDFs, but this is not guaranteed.

Beneficiary object

There are 3 kinds of beneficiaries: person, trust and company. Each has a distinct set of fields, with the exception of share which appears in all 3. There is no restriction on the number of beneficiaries or the combinations of types.

Person

{
  "type" : "person",
  "first_name" : "Jeff",
  "last_name" : "Chen",
  "address" : {
    "street_line_1" : "123 Main St",
    "city" : "San Francisco",
    "state" : "CA",
    "zipcode" : "94107"
  },
  "email" : "jchen@ladderlife.com",
  "relationship" : "husband",
  "social_security_number" : "123-45-6789",
  "date_of_birth" : "1989-08-28",
  "share" : 100,
  "phone" : "(321) 456-7890"
}

Fields

Field	Type	Optional	Description
`type`	`string`		In this case, `person`
`email`	`string`		The beneficiary's email
`first_name`	`string`		The beneficiary's first name
`middle_name`	`string`	Yes	The beneficiary's middle name
`last_name`	`string`		The beneficiary's last name
`relationship`	`string`		One of the allowed beneficiary relationships - see below.
`date_of_birth`	`string`		The date of birth of the beneficiary in `YYYY-MM-DD` format.
`phone`	`string`	Yes	The US phone number of the beneficiary in `(NNN) NNN-NNNN` format.
`address`	address object		The US address of the beneficiary.
`social_security_number`	`string`	Yes	The social security number of the beneficiary in `NNN-NN-NNNN` format.
`share`	`integer`	Yes	Either an integer between `1` and `100` designating the percentage of the payout for this beneficiary, or missing, indicating the payout is to be split evenly between all the beneficiaries (of the same type).

Valid Relationships

aunt
brother
brother-in-law
daughter
daughter-in-law
domestic-partner
father
father-in-law
fiance
fiancee
grandfather
grandmother
husband
mother
mother-in-law
nephew
niece
other
sister
sister-in-law
son
son-in-law
spouse
uncle
wife

Trust

{
  "type" : "trust",
  "name" : "Family Trust",
  "address" : {
    "street_line_1" : "1000 Rocket Road",
    "city" : "Los Angeles",
    "state" : "CA",
    "zipcode" : "90016"
  },
  "share" : 100,
  "trust_date" : "2020-03-16",
  "trustee" : {
    "first_name" : "Abigail",
    "last_name" : "Yor",
    "date_of_birth" : "1995-12-20"
  }
}

Fields

Field	Type	Optional	Description
`type`	`string`		In this case, `trust`
`name`	`string`		The name of the trust as stated on the trust document
`trust_date`	`string`		The date on the trust document
`trustee`	`object`		Personal details of the trustee. The sub-fields are `first_name` - `string` `middle_name` - `string` - Optional `last_name` - `string` `date_of_birth` - `date` in `YYYY-MM-DD` format
`address`	address object		The mailing address for the trust.
`share`	`integer`	Yes	Either an integer between `1` and `100` designating the percentage of the payout for this beneficiary, or missing, indicating the payout is to be split evenly between all the beneficiaries (of the same type).

Company

Only companies doing business in the US are supported.

{
  "type" : "company",
  "email" : "company@ladderlife.com",
  "share" : 100,
  "company_name" : "The Company Name",
  "ein" : "12-3456789",
  "company_address" : {
    "street_line_1" : "456 18th St",
    "city" : "San Francisco",
    "state" : "CA",
    "zipcode" : "94105"
  },
  "mailing_address" : {
    "street_line_1" : "123 Main St",
    "city" : "San Francisco",
    "state" : "CA",
    "zipcode" : "94107"
  }
}

Fields

Field	Type	Optional	Description
`type`	`string`		In this case, `company`
`company_name`	`string`		The official company name
`ein`	`string`		The company's Employer Identification Number (EIN)
`email`	`string`		The email for the company
`phone`	`string`	Yes	The US phone number for the company in `(NNN) NNN-NNNN` format
`company_address`	address object		The company's principal place of business.
`mailing_address`	address object	Yes
`share`	`integer`	Yes	Either an integer between `1` and `100` designating the percentage of the payout for this beneficiary, or missing, indicating the payout is to be split evenly between all the beneficiaries (of the same type).

Overview

Authentication

Quick start

Progressive enhancement

API Version

Errors

Error object

Ladder JavaScript SDK

Instantiating the Ladder SDK

SDK Interface

API Status

Request parameters

Response

Questions

Question object

Example of supertext and label

More details on answer_options_endpoint

Request parameters

Response

Questions requiring hosted fields

Applications

Application object

Start an application

Request parameters

Response

Get an application

Request parameters

Response

Answer a question

Request parameters

Response

Sign the application

Request parameters

Response

Retrieve the decision for the application

Request parameters

Response

Get all documents for an application

Request Parameters

Response

Payment

Collecting payment information

Updating payment information

Offers

Offer object

POCA amendment object

POCA Quotes object

POCA Quote object

Get an offer

Request parameters

Response

Amend an offer

Get list of POCA quotes

Request Parameters

Response

Patch the current offer

Request Parameters

Response

Displaying the POCA

Reverting the POCA.

Accept an offer

Request parameters

Response

Refuse an offer

Request parameters

Response

Policies

Policy object

Get a policy

Request parameters

Response

Update a policy

Request Parameters

Response

Users

User object

Fields

Get a public token

Request Parameters

Response