# The Guarantors API

> Developer documentation for TheGuarantors Embed API: invites, applications, bonds, webhooks and the sandbox.

- [Quick Start Guide](https://docs.theguarantors.com/quickstart.md)
- [Sandbox Guide](https://docs.theguarantors.com/sandbox.md): How the sandbox differs from live, the properties and units pre-seeded for testing, and how to trigger webhook events yourself.
- [Authentication](https://docs.theguarantors.com/authentication.md): Authenticate your requests with Basic Auth and your API key, and send them to the sandbox or live base URL.
- [Application Lifecycle](https://docs.theguarantors.com/application-lifecycle.md): 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.
- [Metadata](https://docs.theguarantors.com/metadata.md): Attach your own key-value data to invites, invite recipients and the entities created from them, and the rules that data must follow.
- [Pagination](https://docs.theguarantors.com/pagination.md): Page through list endpoints with the page and limit query parameters.
- [Errors](https://docs.theguarantors.com/errors.md): The error response format, the machine-readable error codes and field errors returned by the invite amendment endpoints, and how unknown request fields are handled.
- [Webhooks](https://docs.theguarantors.com/webhooks.md): Subscribe to webhook events, the payload and headers each delivery carries, how to verify its signature, and how to handle retries, duplicates and out-of-order events.
- [Amending an Invite](https://docs.theguarantors.com/amending-an-invite.md): Update an invite's details after creating it, add, update or remove its recipients, and cancel it.
- [Canceling an Application](https://docs.theguarantors.com/canceling-an-application.md): Cancel an application that won't be moving forward, at any point before a bond is issued for it.
- [Contact Us](https://docs.theguarantors.com/contact-us.md): How to reach our developer support team, request an API key or a webhook subscription, and what to include in a support request.
- [Breaking Change Policy](https://docs.theguarantors.com/breaking-change-policy.md)
- [Create an invite](https://docs.theguarantors.com/application-api/invites/create-an-invite.md): Creates an invite and sends an application link to each recipient.
- [Retrieve an invite](https://docs.theguarantors.com/application-api/invites/retrieve-an-invite.md)
- [List invites](https://docs.theguarantors.com/application-api/invites/list-invites.md): Returns a paginated list of invites belonging to the authenticated partner.
- [Update an invite](https://docs.theguarantors.com/application-api/invites/update-an-invite.md): Updates the property, unit, coverage level, lease terms, or metadata of an invite. Only fields present in the request are changed. An invite can be amended as long as it hasn't been canceled, expired, or converted into an application. Changing only metadata doesn't send an invite.updated webhook.
- [Cancel an invite](https://docs.theguarantors.com/application-api/invites/cancel-an-invite.md): Cancels an invite that has not yet converted to an application. Returns 409 once conversion has started.
- [invite.updated](https://docs.theguarantors.com/application-api/invites/inviteupdated.md): An invite is updated, such as through `PATCH /v1/invites/{id}`. Changing only `metadata` doesn't send this event.
- [invite.status.canceled](https://docs.theguarantors.com/application-api/invites/invitestatuscanceled.md): An invite is canceled, such as through `POST /v1/invites/{id}/cancel`.
- [Add an invite recipient](https://docs.theguarantors.com/application-api/invites/add-an-invite-recipient.md): Adds a new recipient to an existing invite. An invite can be amended as long as it hasn't been canceled, expired, or converted into an application.
- [Update an invite recipient](https://docs.theguarantors.com/application-api/invites/update-an-invite-recipient.md): Updates the contact details or metadata of a single invite recipient. Changing email gives the recipient a new link, and the previous link stops working. Sending null on phone_number or metadata clears it. An invite can be amended as long as it hasn't been canceled, expired, or converted into an app…
- [Remove an invite recipient](https://docs.theguarantors.com/application-api/invites/remove-an-invite-recipient.md): Removes a recipient from an invite, immediately invalidating their application link. The last remaining recipient on an invite cannot be removed. An invite can be amended as long as it hasn't been canceled, expired, or converted into an application.
- [invite_recipient.added](https://docs.theguarantors.com/application-api/invites/invite_recipientadded.md): A recipient is added to an invite, such as through `POST /v1/invites/{id}/invite-recipients`.
- [invite_recipient.updated](https://docs.theguarantors.com/application-api/invites/invite_recipientupdated.md): An invite recipient is updated, such as through `PATCH /v1/invite-recipients/{id}`. Changing only `metadata` doesn't send this event.
- [invite_recipient.removed](https://docs.theguarantors.com/application-api/invites/invite_recipientremoved.md): A recipient is removed from an invite, such as through `DELETE /v1/invite-recipients/{id}`. Their invite link stops working.
- [Retrieve an application](https://docs.theguarantors.com/application-api/applications/retrieve-an-application.md)
- [Retrieve an application by invite](https://docs.theguarantors.com/application-api/applications/retrieve-an-application-by-invite.md)
- [Cancel an application](https://docs.theguarantors.com/application-api/applications/cancel-an-application.md): Cancels an application that has not yet been bound and sends an `application.status.canceled` webhook. Returns 409 once a bond has been issued. Canceling an application that is already canceled returns 200 with the application unchanged.
- [application.status.started](https://docs.theguarantors.com/application-api/applications/applicationstatusstarted.md): An application is created from an invite.
- [application.status.submitted](https://docs.theguarantors.com/application-api/applications/applicationstatussubmitted.md): Every applicant on the application has submitted their portion of it.
- [application.status.pending](https://docs.theguarantors.com/application-api/applications/applicationstatuspending.md): TheGuarantors needs more information from an applicant after submission. The application stays pending until it moves forward, for example to approved or denied.
- [application.status.approved](https://docs.theguarantors.com/application-api/applications/applicationstatusapproved.md): An application is approved for bonding.
- [application.status.denied](https://docs.theguarantors.com/application-api/applications/applicationstatusdenied.md): An application is denied.
- [application.status.canceled](https://docs.theguarantors.com/application-api/applications/applicationstatuscanceled.md): An application is canceled, either through `POST /v1/applications/{id}/cancel` or by TheGuarantors.
- [Retrieve an applicant](https://docs.theguarantors.com/application-api/applicants/retrieve-an-applicant.md)
- [applicant.status.started](https://docs.theguarantors.com/application-api/applicants/applicantstatusstarted.md): An invite recipient opens their invite link and starts their questionnaire.
- [applicant.status.submitted](https://docs.theguarantors.com/application-api/applicants/applicantstatussubmitted.md): An applicant submits their portion of the application.
- [Retrieve a bond](https://docs.theguarantors.com/application-api/bonds/retrieve-a-bond.md)
- [List bonds for an application](https://docs.theguarantors.com/application-api/bonds/list-bonds-for-an-application.md)
- [bond.status.issued](https://docs.theguarantors.com/application-api/bonds/bondstatusissued.md): A bond is issued for an approved application.
- [bond.status.canceled](https://docs.theguarantors.com/application-api/bonds/bondstatuscanceled.md): An issued bond is canceled.
- [Trigger a sandbox webhook](https://docs.theguarantors.com/application-api/webhooks/trigger-a-sandbox-webhook.md): Advances a sandbox entity to its next state and delivers the matching webhook. Sandbox only.
- [Invite](https://docs.theguarantors.com/schemas/invite.md): An invitation made to prospective residents to apply for a Lease Guarantee and/or Security Deposit Replacement surety bond backed by TheGuarantors.
- [InviteRecipient](https://docs.theguarantors.com/schemas/invite-recipient.md): A prospective resident who has been invited to apply to TheGuarantors.
- [Lease](https://docs.theguarantors.com/schemas/lease.md): The legal contract between a property manager and the tenant. A lease agreement contains information about the property, the address and duration of the lease, and financial terms like rent amount and security deposit information. Leases map 1:1 with TheGuarantors surety bonds. A single lease can ha…
- [Address](https://docs.theguarantors.com/schemas/address.md): A street address, used for lease unit addresses and property primary addresses.
- [Coverage](https://docs.theguarantors.com/schemas/coverage.md): Defines the amount of rent and/or security deposit replacement for the surety bond.
- [Application](https://docs.theguarantors.com/schemas/application.md): An application to get a Lease Guarantee and/or Security Deposit Replacement surety bond. An application can have one or more applicants.
- [Applicant](https://docs.theguarantors.com/schemas/applicant.md): An individual who submits a rental application to be considered for occupancy on a specific lease.
- [Bond](https://docs.theguarantors.com/schemas/bond.md): A Lease Guarantee and/or Security Deposit Replacement surety bond.
- [Principal](https://docs.theguarantors.com/schemas/principal.md): An individual who has a Lease Guarantee and/or Security Deposit Replacement surety bond with TheGuarantors. This individual is one of the future residents or tenants and is associated with the lease.
- [Error](https://docs.theguarantors.com/schemas/error.md): Describes an error encountered while processing a request. It provides a message to help identify the cause and context of the failure.
- [Changelog](https://docs.theguarantors.com/changelog.md): New features and changes to TheGuarantors API.

## OpenAPI Specs

- [application-api](/openapi/application-api.json)