Multi-Applicant Flows

A multi-applicant flow lets more than one person apply together, such as a borrower and a co-borrower. The person who starts the application is the primary applicant; each additional person is a co-borrower, with a role named coborrower_1, coborrower_2 and so on.

Each co-borrower gets their own application on a child product: a separate Product Studio product designed for co-borrowers. LendAPI links all the applications together, copies co-borrower answers back to the primary application, and shows the whole group in the Agent Dashboard.

Choose a flow type

Key concepts

• Primary applicant: the applicant who starts the application. Role primary.
• Co-borrower role: coborrower_1, coborrower_2, ... You add roles in Settings. Each role has its own email (and optional phone) variable.
• Parent product: the product the primary applicant uses.
• Child product: the product each co-borrower completes. It uses plain variable codes such as first_name.
• Co-borrower variables: copies of variables with a __N suffix, where N is the role number. For example, first_name__1 holds co-borrower 1's first name on the primary application.
• Trigger page: the parent product page where co-borrower applications are created.

How it works

flowchart TD
    P1[Primary fills trigger page] --> C[LendAPI creates one child application per selected role]
    C --> B{Flow type}
    B -->|Branched| I[Invite email/SMS sent to each co-borrower]
    I --> CB[Co-borrowers complete child product]
    CB --> N[Primary notified when all are complete]
    N --> R[Primary continues at Next Step]
    B -->|Inline| L[Same session moves through coborrower_1, then coborrower_2, ...]
    L --> R

How data is shared

• Before the child application is created, any primary variable ending in __N is copied into co-borrower N's application without the suffix. For example, if the primary page collects email__1, co-borrower 1's application starts with email filled in.
• Every time a co-borrower saves a page, their answers are copied onto the primary application with the __N suffix. Decision trees on the parent product can then use values such as credit_score__1.
• Decision trees on the child product run on the co-borrower's own application and use plain codes, such as credit_score.

Templates

In email, SMS, document and contract templates, write __0 to mean "this applicant's own value". For example, {{first_name__0}} renders as first_name__1 for co-borrower 1, and as plain first_name for the primary applicant.

Set it up

Setup has four parts: roles, variables, the product, and the trigger page.

1. Turn on multi-applicant and add roles

1. Create an email variable for each co-borrower first, for example email__1 and email__2, in Model Studio. Optionally create phone variables such as mobile__1.
2. Go to Settings → Configuration and find the Multi Applicant section ("Fork products to run applications from multiple applicants at once").
3. Turn on the switch and add a row for each co-borrower. Roles are named automatically (coborrower_1, coborrower_2, ...).
4. For each row, choose the Email variable (required) and optionally the Phone variable.
5. Save.

There is no fixed maximum number of roles.

2. Create co-borrower variables

In Workflows → Model Studio, the table now has an Instance column and one checkbox column per role, headed Co Borrower 1, Co Borrower 2 and so on. Tick a variable in a role's column and click Save Changes to create its __N copy. For example, ticking annual_income under Co Borrower 1 creates annual_income__1.

Unticking deletes the copy. You can't untick a variable that a decision tree still uses.

3. Link the child product

1. Build the co-borrower product in Product Studio, using plain variable codes (first_name, annual_income, ...).
2. Open the parent product's Settings, then the General tab.
3. Turn on Co-Applicant flow ("Allow multiple applicants to submit a single application together") and choose the child product in Select product. Products that already have Co-Applicant flow turned on can't be chosen as a child.

4. Configure the trigger page

1. In the parent product's editor, open the page where co-borrowers should be created.
2. In the page's settings panel, find the Child Product section and click Configure.
3. In Configure Multi Applicant Flow, choose Inline or Branched, then fill in the fields below.
4. Click Save Changes, then publish the product.

🚧

One child product configuration per product

Only one page per product can have a child product configuration. If more than one does, publishing is blocked.

Work with co-borrower applications

View co-borrowers in the Agent Dashboard

• Role switcher. The application header shows a role chip (primary, coborrower_1, ...). Use it to jump between linked applications.
• Overview tab. Shows the application's Role. On the primary application, the Child Product Overview section lists the child Product and, for each co-borrower, the Role (with links to their application and portal), Status and Outcome.
• Data tab. The primary application holds all co-borrower __N values next to the primary's own values.

Each co-borrower application is a full application with its own stage, documents and activity, so your team can work it like any other.

Use the API

There is no separate multi-applicant endpoint. Co-borrower applications are standard applications, so you can read each one with Get an application. In the response's data object, role holds the applicant's role (primary or coborrower_N), and coborrower_applications lists the linked applications by role, each with its application_id.

📘

API key used for co-borrowers

LendAPI creates co-borrower applications using your workspace's API key. If your workspace has no API key, one named after your workspace (ending in "- API Key") is created automatically the first time co-borrower applications are created. You'll see it under Settings → API.

Access and best practices

Permissions

• Turning on multi-applicant and mapping roles: Settings.
• Co-borrower variables: Model Studio.
• Linking products and configuring pages: Product Studio.

See Roles and Permissions.

Best practices

• Collect co-borrower contact details on the primary pages. The invite (in Branched mode) goes to the role's email variable (for example email__1). If it's empty, no application is created for that role.
• Keep the child product's codes plain. Use first_name, not first_name__1, in the child product. The suffix is added automatically when values are copied to the primary.
• Place the Pause Point before decisions that need co-borrower data, so the primary's decision tree runs only after every co-borrower has finished.
• Use __0 in shared templates so one template works for every applicant.

Related guides