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

# Amending an Invite

> Update an invite's details after creating it, add, update or remove its recipients, and cancel it.

After creating an invite, you can update its details and add, update or remove its recipients. An invite can be amended as long as it hasn't been canceled, expired, or converted into an application. If an invite is no longer needed, you can [cancel it](#canceling-an-invite). The examples below use the [pre-seeded sandbox entities](https://docs.theguarantors.com/sandbox.md#pre-seeded-sandbox-entities).

Each amendment that changes the invite or one of its recipients sends the matching webhook to your subscribed endpoint: `invite.updated`, `invite_recipient.added`, `invite_recipient.updated` or `invite_recipient.removed`. A request that changes only `metadata`, or doesn't change anything, doesn't send one. See [Webhooks](https://docs.theguarantors.com/webhooks.md).

Errors from these endpoints include a machine-readable `error_code`, and a `validation_error` lists each rejected field in `field_errors`. See [Error codes](https://docs.theguarantors.com/errors.md#error-codes).

## Updating an Invite

**Endpoint:** [`PATCH /v1/invites/:id`](https://docs.theguarantors.com/application-api/invites/update-an-invite)

**Purpose:** Updates the property, unit, coverage level, lease terms or metadata of an invite. Only the fields you send are changed.

**Example Request**

```
PATCH /v1/invites/inv_abc123
Authorization: Basic <your-api-key>
Content-Type: application/json

{
  "coverage_level": "medium",
  "lease": {
    "end_date": "2027-08-31",
    "monthly_rent": 160000
  }
}
```

**Example Response**

```json theme={null}
{
  "id": "inv_abc123",
  "property_id": "prop_ve2x7i0j6psdizy7",
  "obligee": "Acme Property Management LLC",
  "status": "created",
  "application_id": null,
  "lease": {
    "start_date": "2026-03-01",
    "end_date": "2027-08-31",
    "monthly_rent": 160000,
    "unit_address": {...},
    "object": "lease"
  },
  "invite_recipients": [...],
  "metadata": {},
  "object": "invite"
}
```

To move the invite to a different unit, send its `unit_id` (for example, `unit_u7yr0vt3r9yk0c`) or a new `lease.unit_address`. To move it to a different property, send the new `property_id` together with a `unit_id` or a complete `lease.unit_address`.

## Adding a Recipient

**Endpoint:** [`POST /v1/invites/:id/invite-recipients`](https://docs.theguarantors.com/application-api/invites/add-an-invite-recipient)

**Purpose:** Adds a recipient to the invite. The response includes the new recipient's invite link.

**Example Request**

```
POST /v1/invites/inv_abc123/invite-recipients
Authorization: Basic <your-api-key>
Content-Type: application/json

{
  "first_name": "Jordan",
  "last_name": "Lee",
  "email": "jordan.lee@example.com",
  "phone_number": "+12125551236",
  "metadata": {
    "pms_reference": "occupant-3"
  }
}
```

**Example Response**

```json theme={null}
{
  "id": "ivre_def456",
  "link": "https://qualify.sandbox.theguarantors.com/invite/sign-up/k3v9q2m7x1p4r8tz",
  "first_name": "Jordan",
  "last_name": "Lee",
  "email": "jordan.lee@example.com",
  "phone_number": "+12125551236",
  "metadata": {
    "pms_reference": "occupant-3"
  },
  "object": "invite_recipient"
}
```

## Updating a Recipient

**Endpoint:** [`PATCH /v1/invite-recipients/:id`](https://docs.theguarantors.com/application-api/invites/update-an-invite-recipient)

**Purpose:** Updates a recipient's `first_name`, `last_name`, `email`, `phone_number` or `metadata`. Changing `email` gives the recipient a new `link`, and the previous link stops working. The new email can't already be used by another recipient on the invite. Sending `null` for `phone_number` or `metadata` clears it.

**Example Request**

```
PATCH /v1/invite-recipients/ivre_def456
Authorization: Basic <your-api-key>
Content-Type: application/json

{
  "first_name": "Jordyn",
  "phone_number": null
}
```

**Example Response**

```json theme={null}
{
  "id": "ivre_def456",
  "link": "https://qualify.sandbox.theguarantors.com/invite/sign-up/k3v9q2m7x1p4r8tz",
  "first_name": "Jordyn",
  "last_name": "Lee",
  "email": "jordan.lee@example.com",
  "phone_number": null,
  "metadata": {
    "pms_reference": "occupant-3"
  },
  "object": "invite_recipient"
}
```

## Removing a Recipient

**Endpoint:** [`DELETE /v1/invite-recipients/:id`](https://docs.theguarantors.com/application-api/invites/remove-an-invite-recipient)

**Purpose:** Removes the recipient from the invite. Their invite link stops working immediately. A successful request returns `204 No Content` with an empty body.

**Example Request**

```
DELETE /v1/invite-recipients/ivre_def456
Authorization: Basic <your-api-key>
```

## Canceling an Invite

An invite can be canceled at any point before it converts into an application. Canceling an invite is how you retire an invite that is no longer valid, for example when the prospective resident withdraws, the unit is leased to someone else, or the invite was created by mistake.

**Endpoint:** [`POST /v1/invites/:id/cancel`](https://docs.theguarantors.com/application-api/invites/cancel-an-invite)

**Purpose:** Cancels an invite that has not yet converted into an application and moves its status to `canceled`. Once canceled, the invite and its recipient links can no longer be used to start an application, and the invite can no longer be amended.

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

**Request Body:** The body is optional. If provided, it may contain a single field:

| Field | Type | Required | Description |
| - | - | - | - |
| `reason` | string | No | A free-form explanation of why the invite is being canceled, between 1 and 1000 characters. The reason is recorded for context only; it is not returned in the response or included in the webhook payload. |

**Response:** The canceled invite, with `status` set to `canceled`.

When the invite is successfully canceled, we will emit an `invite.status.canceled` webhook to your registered URL if you are subscribed for this event type. In the event that the invite had already been canceled, then the operation is effectively a no-op; the endpoint will return with `200` but will not emit a new `invite.status.canceled` webhook.