Application Lifecycle

An application is one applicant's request for one of your products. It holds everything collected about that request: the answers the applicant typed, data returned by integrations (credit bureaus, bank data and so on), decision and pricing results, documents, contracts and an activity history.

Every application belongs to a product (built in Product Studio) and has a stage that tells your team where it is in the process. You can start applications from your hosted application page or from your own system through the API, and your team works them in the Agent Dashboard.

Key concepts

• Application ID: the application's UUID, for example 2d30a4c7-8a8e-4de3-9718-71857993e357. All application API calls use it.
• App number: a shorter numeric ID, returned as app_number. Agents see it in the dashboard.
• Product: the application flow the applicant goes through: its pages, fields, routing and decisions.
• Stage: where the application is in your process, such as Processing, Approved or Document.
• Application data: the application's variables as key/value pairs, for example {"loan_amount": 25000}.
• Activity: a time-stamped log of what happened to the application, including system events such as "Application created using Create API."

How it works

Create an application

You can create an application in two ways.

Hosted product page. Every published product has an application URL. In Product Studio, open a product's row menu and choose Copy URL to copy it, or Launch Application to open it. The applicant fills in the pages you designed. Their answers are saved as they move from page to page, and any decision trees, integrations and stage changes you configured run along the way.

Create Application API. Your system sends the applicant's basic details and a product_id to POST /api/v1/application/. LendAPI creates the application and returns its ID and a redirect_url. You can then:

• send the applicant to redirect_url to continue the remaining pages on the hosted flow, or
• keep everything server-side and add data with the Update API.

When an application is created through the API, LendAPI also:

• creates or updates the applicant's customer profile, matched by email,
• records "Application created using Create API." in the activity log,
• sends any new-application notifications and product email templates you have set up (unless the request includes "suppress_new_app_notification": true).

🚧

One application per email

If your workspace allows only one application per email address, creating a second application with an email that already has one returns Email already in use - try another. Staff user emails cannot be used as applicant emails.

Stages

Every application has exactly one stage at a time. LendAPI provides 12 system stages, and you can add your own custom stages under Settings → Status. That screen lists the System Default stages and your Custom ones. Custom stages can be set from a page in Product Studio, from the Agent Dashboard, or through the API.

What moves an application between stages.

flowchart LR
    New([Application created]) --> Processing
    Processing -->|Decision outcome or agent| Approved
    Processing -->|Decision outcome or agent| Declined
    Processing -->|Decision outcome| Review
    Processing -->|Documents requested| Document
    Review -->|Agent decision| Approved
    Review -->|Agent decision| Declined
    Document -->|Applicant uploads| DocReceived[Doc Received]
    DocReceived -->|All documents reviewed| Processing
    DocReceived -->|Rejected document, new request| Document
    Approved -->|Loan transferred| Booked
    Processing -->|Inactive past withdrawal period| Withdrawn

The diagram shows the common paths. These are the triggers:

• Decision outcomes. When a decision tree runs on a page, its outcome (for example Approve, Decline, Review or Request Docs) sets the stage. See Decision Trees.
• Page settings. A Product Studio page can set a Custom stage. The application moves to that stage when the applicant submits the page.
• Documents. Requesting documents moves the application to Document. Uploads move it to Doc Received. When every requested document has been approved or rejected, the application returns to Processing. See Documents.
• Agents. In the Agent Dashboard, the Update Stage dropdown offers Approve, Decline, Doc Requested, Withdrawn, Closed, Processing and your custom stages.
• Automatic withdrawal. If you turn on Automatic Withdrawal in a product's settings, inactive applications move to Withdrawn.
• API. Your system can set the stage directly (see Update the stage).

Most stage changes are written to the application's activity log. Many also fire webhooks, for example application.approved, application.declined, application.request_docs and application.withdrawn. See Webhooks.

Work applications in the Agent Dashboard

Open Agent Dashboard in the left sidebar to see your applications list. Select an application to open its detail view. A side panel shows Overview, Tasks and Notes for the application. Which tabs each user can see depends on their role.

Use the API

All endpoints use your API key as Authorization: Bearer <key>. A key that starts with live_ works on live data; any other key (for example test_...) works on sandbox data. See Authentication and Sandbox and Live.

Create an application via API

Optional fields include middle_name, address1, address2, city, state, zipcode, mobile, ssn, birth_date (format MM/DD/YYYY), lead_id, tenant_id (a sub-tenant's UUID), tag_names (up to three tags) and data (any other variables).

curl -X POST https://app.lendapi.com/api/v1/application/ \
  -H "Authorization: Bearer test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 123,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "mobile": "5550100100",
    "birth_date": "01/15/1990",
    "data": {"loan_amount": 25000, "loan_term": 36}
  }'

{
  "object": "application",
  "url": "api/v1/application/",
  "id": "2d30a4c7-8a8e-4de3-9718-71857993e357",
  "app_number": 10452,
  "customer_id": 8812,
  "redirect_url": "https://app.lendapi.com/v2/application/product/abc123/2d30a4c7-8a8e-4de3-9718-71857993e357/?test_mode=1"
}

If your product has derived variables that depend on values you send in data, add "recompute_derived_vars": true to calculate them when the application is created.

Update an application

PUT /api/v1/application/ takes the application id and a data object. The keys in data are merged into the application's existing values; keys you don't send are left unchanged. The response returns the application's full data.

{
  "id": "2d30a4c7-8a8e-4de3-9718-71857993e357",
  "data": {"annual_income": 85000, "employer_name": "Example Corp"}
}

Update the stage

Send the application ID as session and the stage number as stage. System stage numbers are: 0 Processing, 1 Approved, 2 Declined, 3 Document, 4 Review, 5 Booked, 6 Withdrawn, 7 Doc Received, 8 Completed, 9 Default, 10 Closed, 11 Pre-Qualify. Custom stages use the numbers shown under Settings → Status.

{"session": "2d30a4c7-8a8e-4de3-9718-71857993e357", "stage": 4}

{"code": 1, "msg": "Status updated"}

A successful call also logs the change in the application's activity.

📘

Workspace checks

Every application endpoint checks that the application belongs to the workspace that owns the API key. An application from another workspace returns 403 Permission denied.

Access and best practices

Permissions

The Agent Dashboard and each of its tabs are controlled by the Agent Dashboard module in roles. See Roles and Permissions.

Best practices

• Use sandbox keys while you build. Applications created with a test key stay in sandbox, and their redirect_url opens the flow in test mode.
• Store the application ID. Save the id from the create response; every other call needs it.
• Use webhooks instead of polling. Subscribe to stage events rather than calling Get Application on a schedule.
• Send variables by their codes. Keys in data must match your variable codes exactly (for example loan_amount, not Loan Amount). Unknown keys are stored but nothing in your flow will use them.
• Send dates as MM/DD/YYYY. A birth_date in any other format is rejected.

Related guides