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

# Manage an Application via the API

## Manage an Application via the API

Use this guide after creating an application to manage the deal through its full API lifecycle: update application data, upload documents, run underwriting, create placements and offers, close the deal, and record funding activity.

Before you begin, you need:

* An [integration token](/lendflow-external/docs/integration-tokens) with the required application and workflow permissions, or a Bearer token from the [Get Bearer Token](/api-reference/authentication/get-bearer-token) endpoint.
* The application UUID returned when the application was created.
* A [Workflow Builder template](/lendflow-external/docs/what-is-the-workflow-builder) configured with the stages and Builders your process uses.

## Application lifecycle

Follow the stages configured in the application's workflow. A typical API-managed deal follows this sequence:

1. Retrieve and update the application.
2. Upload bank statements, the signed application, and other required documents.
3. Advance the deal to the **Underwriting** stage and run Data Orchestration.
4. Advance the deal to the **Scorecards** stage and run Scorecards.
5. Advance the deal to the **Placement** stage.
6. Create and manage lender placements.
7. Create, share, and manage offers.
8. Accept an offer and advance the deal to closing.
9. Confirm the final offer terms and advance the deal to funded.
10. Record funding transactions when the funded product supports them.

Your workflow may include additional stages. Retrieve the application's stage IDs and follow the configured order instead of assuming every workflow uses the same sequence.

## 1. Retrieve the application

Call [Get Application](/api-reference/workflow-management/get-application) with the application UUID. Use the response to confirm the application's current information before sending an update.

Re-retrieve the application after asynchronous operations or webhook notifications so your integration acts on the latest saved state.

## 2. Update application data

Application fields depend on the workflow template assigned when the deal was created.

1. Call [Sample Payload - Workflow](/api-reference/workflow-management/sample-payload--workflow) to retrieve the expected fields for the application.
2. Send the fields that changed to [Update Application Workflow Data](/api-reference/workflow-management/update-application-workflow-data).
3. Retrieve the application again to confirm the saved values.

Use the application-file endpoint in the next section for documents. Do not replace complete business or owner objects with partial data unless the endpoint schema identifies the fields as safe to omit.

## 3. Upload application documents

### Upload and categorize files

Use [Upload Multiple Application Files](/api-reference/documents/upload-multiple-application-files) for bank statements, signed applications, and other application documents.

The current route is:

```http theme={"system"}
POST /api/applications/{application_id}/files/multiple
```

Send each document under `files` with its `file`. Do not specify `file_type`, and omit `skip_categorization`. Lendflow categorizes each file by its contents and assigns the appropriate type, including bank statements and signed applications.

<Note>
  Set `skip_categorization` only when your integration intentionally needs to preserve a supplied category. For the standard upload flow, omit the flag and let Lendflow categorize the files.
</Note>

### Retrieve uploaded documents

1. Use [List Application Files](/api-reference/documents/list-application-files) to retrieve the current file IDs and categories.
2. Use [Download Application File](/api-reference/documents/download-application-file) to download a specific file.

Configure the **Any Document Uploaded** event in [Custom Workflow Webhooks](/lendflow-external/docs/custom-workflows-webhooks) when your integration should react to new documents.

## 4. Move through workflow stages

Retrieve the application's configured stages with [Show Workflow Stages](/api-docs/reference/get-api-v2-workflow-applications-application-id-stages). Each stage includes an ID, name, and stage type.

Use [Move to Next Workflow Stage](/api-reference/workflow-management/move-to-next-workflow-stage) to advance through the configured flow one stage at a time. This is the preferred transition because it follows the application's workflow order and stage validation.

<Warning>
  Do not use a workflow status or sub-status to move the application. Stages determine the application's position in the workflow. Statuses and sub-statuses describe its current state within that workflow.
</Warning>

Use [Get Workflow Status](/api-reference/workflow-management/get-workflow-status) to retrieve configured status choices. Use [Update Workflow Status](/api-reference/workflow-management/update-workflow-status) to update those labels without changing the stage.

If the deal should no longer proceed, use [Decline Application](/api-reference/workflow-management/decline-application). Declining the application marks the deal as dead; it is not a substitute for declining one placement or offer.

## 5. Run Data Orchestration

Run Data Orchestration when the deal reaches the **Underwriting** stage where the published template is available.

The API flow is:

1. Find a published template compatible with the application and stage.
2. Execute the template for the application.
3. Monitor the asynchronous run through its Data Orchestration log.
4. Use the completed outcome and history in your underwriting decision.

Follow [Data Orchestration via API](/lendflow-external/docs/how-to-run-orchestration-via-api) for the endpoint sequence, master-status values, and webhook option.

## 6. Run Scorecards

After Data Orchestration is complete, advance the application to its separate **Scorecards** stage. Scorecards evaluate information already stored on the application. When the scorecard depends on current provider data, complete Data Orchestration before running the scorecard.

The API flow is:

1. Retrieve the application's **Scorecards** stage ID.
2. List the finished scorecards available for the application and stage.
3. Run selected scorecards or scorecard groups, or omit their ID lists to run all eligible templates.
4. Retrieve the individual or group results after processing finishes.
   Follow [Scorecards via API](/lendflow-external/docs/scorecards-via-api) for the current endpoints, result retrieval, and webhook events.

## 7. Create and manage placements

A placement represents an application sent to a funder for a specific product.

### Create a placement

Call [Create Lender Placement](/api-reference/placements/create-lender-placement) when the application reaches its Placement stage. The request identifies:

* The funder.
* The product.
* The application's Placement stage ID.
* The delivery method, such as API, email, manual, or Lendflow-managed placement.

Additional fields depend on the selected method. For example, email delivery requires recipients and an email body.

### Review and update placements

* Use [List Application Placements](/api-reference/placements/list-application-placements) to list placements.
* Use [Get Application Placement](/api-reference/placements/get-application-placement) to retrieve one placement.
* Use [Update Lender Placement Status](/api-reference/placements/update-lender-placement-status) to update a placement.

A placement must be **Approved** before an offer can be created against it. Declining a placement can retract its associated offers. A placement does not receive a Funded status; funding is represented by the application's Funded workflow stage.

## 8. Create and manage offers

### Create an offer

1. Select an approved placement belonging to the application.
2. Use [List Offer Templates](/api-reference/offer-templates/list-offer-templates) to select the correct template and retain its ID.
3. Retrieve the selected template's expected offer fields.
4. Call [Create Offer](/api-reference/offers/create-offer) with the application UUID, approved `placement_id`, and required `offer_template_id`.
5. Save the offer UUID returned in the response.

Offer fields and closing fields are defined by the selected offer template. Do not maintain a fixed product-field list in your integration.

### Manage the offer

| Action | Endpoint |
| - | - |
| List the application's offers | [List Application Offers](/api-reference/offers/list-application-offers) |
| Retrieve one offer | [Get Offer](/api-reference/offers/get-offer) |
| Update offer terms | [Update Offer](/api-reference/offers/update-offer) |
| Share or unshare offers | [Update Offer Sharing](/api-reference/offers/update-offer-sharing) |
| Accept, decline, retract, or send offers | [Update Multiple Offer Statuses](/api-reference/offers/update-multiple-offer-statuses) |

Offer-status updates are asynchronous. Retrieve the offer after the update completes or process the corresponding offer webhook before continuing.

## 9. Close and fund the deal

Accepting, confirming, and funding an offer are separate actions:

1. Set the selected offer's status to **Accepted**.
2. Advance the application through its configured workflow until it reaches **Closing**.
3. Call [Confirm Offer](/api-reference/offers/confirm-offer) with the final closing fields defined by the offer template.
4. Advance the application through the remaining configured stages until it reaches **Funded**.
5. Retrieve the application and offer to confirm their final state.

Confirming an offer records its final closing terms. It does not accept the offer or move the application to another stage.

<Note>
  [Create a Funded Offer](/api-reference/offers/create-a-funded-offer) is a shortcut for eligible self-funded deals. It creates, accepts, and confirms the offer. Automatic movement to Funded applies to linear workflows; other workflows must still be advanced through their configured stages.
</Note>

## 10. Add funding transactions

Funding transactions record activity after an application is funded. They do not move the application to Funded.

Transactions are currently supported for:

* **Line of Credit**, where a transaction represents a draw.
* **ARLOC**, where a transaction represents an invoice.

The application must already be in the Funded stage. Use the funded offer UUID with the applicable endpoint:

| Action | Endpoint |
| - | - |
| List transactions | [List Funding Transactions](/api-reference/offers/list-funding-transactions) |
| Create a transaction | [Create Funding Transaction](/api-reference/offers/create-funding-transaction) |
| Retrieve one transaction | [Get Funding Transaction](/api-reference/offers/get-funding-transaction) |
| Update a transaction | [Update Funding Transaction](/api-reference/offers/update-funding-transaction) |
| Delete a transaction | [Delete Funding Transaction](/api-reference/offers/delete-funding-transaction) |

Creating a transaction requires `transaction_amount` and `transaction_date`. Additional fields, such as payment terms, invoice due date, commission, or accounting code, depend on the transaction.

## Use webhooks throughout the flow

Use [Custom Workflow Webhooks](/lendflow-external/docs/custom-workflows-webhooks) to notify your integration when applications, documents, underwriting runs, placements, and offers change.

For every event:

1. [Verify the webhook signature](/lendflow-external/docs/verifying-webhook-authenticity).
2. Use the payload to identify the application or related resource.
3. Retrieve the current resource from the API.
4. Apply an idempotent update so duplicate webhook delivery does not repeat the action.

## FAQ

<AccordionGroup>
  <Accordion title="What is the difference between a workflow stage and a workflow status?">
    A stage identifies where the application is in the configured process. A status or sub-status describes the application's state without moving it to another stage.
  </Accordion>

  <Accordion title="Should Data Orchestration run before Scorecards?">
    Run Data Orchestration first when the scorecard requires current Data Services results. A scorecard evaluates information already stored on the application and does not request new provider data.
  </Accordion>

  <Accordion title="What is the difference between a placement ID and an offer ID?">
    A placement identifies the opportunity sent to a funder for a product. An offer belongs to an approved placement and receives its own ID when created.
  </Accordion>

  <Accordion title="Does confirming an offer close or fund the application?">
    No. Confirming records final closing terms. Accept the offer, move the application to Closing, confirm it, and then advance the application through the configured workflow to Funded.
  </Accordion>

  <Accordion title="Does creating a funding transaction fund the deal?">
    No. The application must already be in the Funded stage. A funding transaction records a later Line of Credit draw or ARLOC invoice.
  </Accordion>

  <Accordion title="Should my integration poll or use webhooks?">
    Use webhooks for event-driven processing and retrieve the current resource after each event. Poll asynchronous resources when your integration must control the check interval or when a completion webhook is not configured.
  </Accordion>
</AccordionGroup>

## Next steps

<Card title="Submit a New Application via the API" icon="file-circle-plus" href="/api-docs/docs/submit-a-new-application-via-the-api" horizontal>
  Create the application that starts this lifecycle.
</Card>

<Card title="Data Orchestration via API" icon="diagram-project" href="/lendflow-external/docs/how-to-run-orchestration-via-api" horizontal>
  Run underwriting data and decision flows.
</Card>

<Card title="Scorecards via API" icon="chart-simple" href="/lendflow-external/docs/scorecards-via-api" horizontal>
  Run scorecards and retrieve their results.
</Card>

<Card title="Configure Custom Workflow Webhooks" icon="webhook" href="/lendflow-external/docs/custom-workflows-webhooks" horizontal>
  Receive lifecycle notifications in your integration.
</Card>