Application Lifecycle

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 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.

Application statuses: started, submitted, pending, approved or denied, and bound once a bond is issued

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

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 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

{
  "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 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. 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

{
  "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.

Get Started

Core Concepts

Guides

Resources

Accessing Entities Through the Application Lifecycle

Get Application by Invite ID

List Bonds by Application ID

Navigating the Lifecycle Summary

​Accessing Entities Through the Application Lifecycle

​Get Application by Invite ID

​List Bonds by Application ID

​Navigating the Lifecycle Summary

Accessing Entities Through the Application Lifecycle

Get Application by Invite ID

List Bonds by Application ID

Navigating the Lifecycle Summary