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

# Application Lifecycle

> How an invite becomes an application and then a bond, the statuses an application moves through, and how to retrieve each entity from the one before it.

Integrating with our APIs offers two key benefits: the ability to create invitations automatically and pre-fill the renter questionnaire with lease details, and the ability to monitor an applicant's application status with TheGuarantors as the applicant progresses through the bond application process. Our [webhooks](https://docs.theguarantors.com/webhooks.md) provide real-time updates to all subscribed listeners.

For instance, when an applicant uses the invite link and completes our questionnaire, an event is emitted confirming the application submission. Likewise, an event is sent at every critical juncture of the application lifecycle, whether the application is approved, denied, or a bond is issued to the applicant. In some cases we may need additional information from the applicant after they have submitted their application with us. When that happens, their application status is set to pending, and you will receive the corresponding webhook update until the application moves forward again (for example, to approved or denied).

An application can also be canceled at any point before a bond is issued, either by you through `POST /v1/applications/:id/cancel` or by TheGuarantors. When that happens, its status is set to canceled and you will receive an `application.status.canceled` webhook. See [Canceling an Application](https://docs.theguarantors.com/canceling-an-application.md).

![Application statuses: started, submitted, pending, approved or denied, and bound once a bond is issued](https://mintcdn.com/theguarantors-2e3c1083/I_TMYtCDA-gwmmQ0/images/application-lifecycle/application-statuses.png?fit=max\&auto=format\&n=I_TMYtCDA-gwmmQ0\&q=85\&s=51646569a66a58dfd121045adb5ac6b0)

The application lifecycle can also be thought of as the transformation of an invite and its recipients to the application and its applicants and ultimately to a bond and its principals. As a result, many fields on each entity are inherited or derived from the entity that precedes it.

![The invitation, application, approval and bond issuance phases, and the events that move an invite to an application and an application to a bond](https://mintcdn.com/theguarantors-2e3c1083/I_TMYtCDA-gwmmQ0/images/application-lifecycle/entity-phases.png?fit=max\&auto=format\&n=I_TMYtCDA-gwmmQ0\&q=85\&s=3b7e3a5aff3ca8a68d5d99848c4eb173)

With our applicant level webhooks, we also provide the ability to track the progress of individual applicants as they progress through our system. Currently, we provide an `applicant.status.started` webhook that notifies users of when an individual applicant has started their application and an `applicant.status.submitted` webhook when an individual applicant has submitted their application.

## Accessing Entities Through the Application Lifecycle

As described above, the application lifecycle follows a progression: **Invite** → **Application** → **Bond**.

To more easily navigate this chain, we have provided the following endpoints that enable our users to retrieve the next entity using the ID of the preceding one.

### Get Application by Invite ID

After an invite is created and the applicant starts their application (the `application.status.started` event), you can retrieve the resulting Application using the Invite ID.

**Endpoint:** [`GET /v1/invites/:invite_id/application`](https://docs.theguarantors.com/application-api/applications/retrieve-an-application-by-invite)

**Purpose:** Retrieves the application object linked to a specific invite ID.

**Path Parameter:** `invite_id` (string, required) is the unique identifier for the invite.

**Example Request**

```
GET /v1/invites/inv_abc123/application
Authorization: Basic <your-api-key>
```

**Example Response**

```json theme={null}
{
  "id": "sd_xyz789",
  "status": "started",
  "invite_id": "inv_abc123",
  "bond_id": null,
  "lease": {
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "monthly_rent": 200000,
    "unit_address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "object": "address"
    },
    "object": "lease"
  },
  "applicants": [...],
  "metadata": {},
  "object": "application"
}
```

### List Bonds by Application ID

After an application is approved and a bond is issued (`bond.status.issued` event), retrieve all bonds associated with that application using our [`GET /v1/applications/:application_id/bonds`](https://docs.theguarantors.com/application-api/bonds/list-bonds-for-an-application) endpoint.

**Description:** Retrieves a paginated list of all bonds issued for a specific application, ordered by issue date with the most recent bond appearing first. The first bond in the list is the one currently in effect for the application.

An application usually has a single bond. If its bond is amended after it has been issued, for example to reflect a change to the lease, the original bond is canceled and a replacement bond is issued in its place. The list returns both: the replacement, with status `issued`, first, followed by the original, with status `canceled`.

**Path Parameters:** `application_id` (string): The unique identifier of the Application.

**Query Parameters:** `page` (integer): Specifies the page number for pagination (Default: 1). `limit` (integer): Specifies the number of bonds to return per page (Default: 10). See [Pagination](https://docs.theguarantors.com/pagination.md).

**Response:** A paginated list of bond objects associated with the application.

**Example Request**

```
GET /v1/applications/sd_xyz789/bonds?page=1&limit=10
Authorization: Basic <your-api-key>
```

**Example Response**

```json theme={null}
{
  "total_items": 1,
  "total_pages": 1,
  "current_page": 1,
  "items_per_page": 10,
  "items": [
    {
      "id": "bond_def456",
      "application_id": "sd_xyz789",
      "status": "issued",
      "document_link": "https://api.theguarantors.com/v1/bonds/bond_def456/document?token=v1.xxxxx",
      "obligee": "Gentry Apts. LLC",
      "lease": {...},
      "principals": [...],
      "coverage": {...},
      "metadata": {...},
      "object": "bond"
    }
  ]
}
```

### Navigating the Lifecycle Summary

The following steps outline the sequence of API calls to retrieve an Applicant's bond information:

**1. Start (Create Invite)**

* **Action:** `POST /v1/invites`
* **Entity Retrieved:** Invite

**2. Get Application**

* **Action:** `GET /v1/invites/:invite_id/application`
* **Entity Retrieved:** Application

**3. Get Bonds**

* **Action:** `GET /v1/applications/:application_id/bonds`
* **Entity Retrieved:** Bond(s)

This pattern allows you to track the progression of an application through each stage in our system from creation to bonding.