# RentEngine Public API

Integrate your systems anywhere with RentEngine.

## Authorization

This API uses JWT Bearer token authentication. Follow these steps to obtain and use your API tokens:

### Obtaining API Tokens

1. Log in to your RentEngine [developer portal](https://app.rentengine.io/developer/portal)
2. In the top corner, click the "Create New API Key" button
3. Provide a name for your token (e.g., "Integration Name")
4. Click Create
5. Copy the token to your clipboard and save it securely as it will not be displayed again

**Important Security Notice:** Your token will only be displayed ONCE at creation time. Make sure to copy it and store it securely. For security reasons, we cannot display the token again after this point.

### Using API Tokens

Include your token in all API requests as a Bearer token in the Authorization header:

```
Authorization: Bearer your_token_here
```

### Token Security Best Practices

- Store tokens securely in environment variables or a secure vault
- Never hardcode tokens in your application code
- Do not share tokens in public repositories or client-side code
- Use separate tokens for different integrations or environments

### Token Permissions

Each token generated by a user will have the full permissions of the user that created it across all accounts associated with that user. 
Actions will be logged in the name of that user & token. 

### Invalidating Tokens

Tokens will not expire. (Well not for 100 years at least). If a token is compromised or no longer needed:

1. Log in to your RentEngine [developer portal](https://app.rentengine.io/developer/portal)
2. Find the token you wish to invalidate in the table in the API Keys section
3. Click the "Revoke Token" icon that looks like a trash can

Once revoked, a token cannot be restored. You'll need to create a new token if needed.

### Pagination

All list endpoints in the RentEngine API support pagination to efficiently handle large datasets. Here's how to use pagination in your API requests:

**Pagination Parameters**

When making requests to list endpoints (e.g., `/lockboxes`, `/lockbox_events`, `/units`), you can include the following query parameters:

- `limit` - Controls how many items to return per page (default: 50, max: 100)
- `page_number` - Specifies which page to retrieve (0-indexed, default: 0)

Example request with pagination:
```
GET /api/public/v1/lockboxes?limit=25&page_number=1
```

This would return the second page of results with 25 items per page.

**Response Format**

Paginated responses include only the requested data. The total number of items across all pages is not included in the response. 

**Iterating Through Pages**

To retrieve all items across multiple pages, increment the `page_number` parameter until you've processed all pages. You can determine when you've reached the end when the response is shorter than the limit requested.

**Performance Considerations**

- Use appropriate `limit` values based on your needs. Smaller values reduce payload size but require more API calls, which can slow down performance and be subject to rate limits.
- When filtering data, apply filters in the query parameters first to reduce the total number of items that need to be fetched.

## Webhooks

RentEngine provides webhooks to notify your systems about events in real-time. This allows you to build integrations that respond immediately to changes in your RentEngine data.

**Setting Up Webhooks**

Webhooks can be configured through the RentEngine [developer portal](https://app.rentengine.io/developer/portal). You'll need to specify:

1. The target URL where webhook events should be sent
2. The data you want to monitor (e.g., lockboxes, units, lockbox_events)
3. The event types you want to receive (INSERT, UPDATE, DELETE)
4. An optional API key that will be included in webhook requests to your endpoint

**Webhook Payload Structure**

Webhook payloads follow this general structure:

```json
{
  "type": "INSERT|UPDATE|DELETE",
  "table": "table_name",
  "record": { /* The current state of the record (null for DELETE) */ },
  "old_record": { /* The previous state of the record (null for INSERT) */ }
}
```

The specific fields in `record` and `old_record` will depend on the table that triggered the event.

**Event Types**

- `INSERT`: Sent when a new record is created
- `UPDATE`: Sent when an existing record is modified
- `DELETE`: Sent when a record is deleted

**Security Considerations**

- Webhook endpoints should be HTTPS to ensure secure transmission of data
- Validate the API key included in the webhook request to ensure it's coming from RentEngine
- Implement idempotency in your webhook handlers to prevent duplicate processing

**Webhook Delivery**

RentEngine uses a reliable delivery system (QStash) to ensure webhooks are delivered even during temporary outages. If your endpoint is unavailable, we'll retry delivery with exponential backoff.


Version: 1.1.1

## Servers

Production environment
```
https://app.rentengine.io/api/public/v1
```

Staging environment
```
https://staging-app.rentengine.io/api/public/v1
```

## Security

### BearerAuth

JWT Bearer token authentication. Use format 'Bearer {token}' in the Authorization header.

Type: http
Scheme: bearer
Bearer Format: JWT

### ApiKeyAuth

API key authentication for webhooks. The key is defined when setting up the webhook in the [developer portal](https://app.rentengine.io/developer/portal).

Type: apiKey
In: header
Name: x-api-token

## Download OpenAPI description

[RentEngine Public API](https://rentengine.redocly.app/_spec/openapi.yaml)

## Lockboxes

Operations for managing lockboxes

### Get lockboxes

 - [GET /lockboxes](https://rentengine.redocly.app/openapi/lockboxes/getlockboxes.md): Retrieve lockboxes with optional filtering and pagination

### Create lockboxes

 - [POST /lockboxes](https://rentengine.redocly.app/openapi/lockboxes/postlockboxes.md): Create new lockboxes (currently only SentriLock type is supported)

### Transfer lockboxes between accounts

 - [POST /lockboxes/transfer_accounts](https://rentengine.redocly.app/openapi/lockboxes/postlockboxestransferaccounts.md): Moves lockboxes between accounts. The user must have access to both the lockboxes and the target account.

### Generate a lockbox code

 - [POST /lockboxes/generate_code](https://rentengine.redocly.app/openapi/lockboxes/postgeneratelockboxcode.md): Generate a one-time code for a lockbox. The code can be generated by providing either a lockbox_id, serial_number, or unit_id. The code will be valid for the specified date.

## Lockbox Events

Operations for tracking and creating lockbox events

### Get lockbox events

 - [GET /lockbox_events](https://rentengine.redocly.app/openapi/lockbox-events/getlockboxevents.md): Retrieve lockbox events with optional filtering and pagination

### Create lockbox events

 - [POST /lockbox_events](https://rentengine.redocly.app/openapi/lockbox-events/postlockboxevents.md): Create new lockbox events (Install or Uninstall)

### Lockbox events

 - [POST LockboxEvents](https://rentengine.redocly.app/openapi/lockbox-events/receive-lockbox-events.md)

## Lockbox Installations

Operations for retrieving lockbox installations

### Get lockbox installations

 - [GET /lockbox_installations](https://rentengine.redocly.app/openapi/lockbox-installations/getlockboxinstallations.md): Retrieve lockbox installations with optional filtering and pagination. Lockbox installations can only be created by inserting a lockbox event with event_type "Install".

## Units

Operations for managing rental units

### Get units

 - [GET /units](https://rentengine.redocly.app/openapi/units/getunits.md): Retrieve units with optional filtering and pagination

### Create or update a unit

 - [POST /units](https://rentengine.redocly.app/openapi/units/postunit.md): Create a new unit or update an existing one.

## Insert vs Update
- : When no  is provided, a new unit will be created. Required fields for creation include , , , and .
- : When an  is provided, an existing unit will be updated. No other fields are required.

## Address Updates
When updating a unit, if you include the  field, you must provide all address components (, , , , ). Partial address updates are not supported.

## Structured Access Instructions
When providing , the  field must also be set. The structure of the access instructions depends on the showing method:
- For "Self Guided", "Remote Guided", or "Remote Guided with Gated Access" methods: Include fields like , , etc.
- For "Accompanied" method: Include fields like , , etc.


### Units

 - [POST UnitsEvents](https://rentengine.redocly.app/openapi/units/receive-units-updates.md): Webhook for unit changes (creates, updates, deletes).
Only the below fields are included in the record and old_record objects.


## Prospects

Events related to prospective tenants

### Get prospects

 - [GET /prospects](https://rentengine.redocly.app/openapi/prospects/getprospects.md): Retrieve prospects with optional filtering and pagination

### Prospects

 - [POST ProspectsEvents](https://rentengine.redocly.app/openapi/prospects/receive-prospects-updates.md): Webhook for prospect changes (creates, updates, deletes).
Only the below fields are included in the record and old_record objects.


## Multifamily Properties

Operations for managing multifamily properties. Multifamily properties are used to syndicate large properties with paid advertising contracts to the paid rental feeds. For example, paid adverising contracts are required for the Zillow network if the building has more than 24 units, and for the Apartments.com if the building has more than 4 units. Other ILSs have different thresholds.

### Get multifamily properties

 - [GET /multifamily_properties](https://rentengine.redocly.app/openapi/multifamily-properties/getmultifamilyproperties.md): Retrieve multifamily properties with optional filtering

### Create or update a multifamily property

 - [POST /multifamily_properties](https://rentengine.redocly.app/openapi/multifamily-properties/postmultifamilyproperties.md): Create a new multifamily property or update an existing one

## Floorplans

Operations for managing floorplans associated with multifamily properties. Floorplans are used to syndicate units to the paid rental feeds for paid advertising contracts. They must be used in conjunction with a multifamily property.

### Get floorplans

 - [GET /floorplans](https://rentengine.redocly.app/openapi/floorplans/getfloorplans.md): Retrieve multifamily_prs with optional filtering

### Create or update a floorplan

 - [POST /floorplans](https://rentengine.redocly.app/openapi/floorplans/postfloorplans.md): Create a new floorplan or update an existing one

## Leasing Events

Events related to leasing events

### Create leasing events

 - [POST /leasing_events](https://rentengine.redocly.app/openapi/leasing-events/postleasingevents.md): Create one or more leasing events. Additional event types will be supported in future releases.
Currently only  events are fully supported.  When using the "Assign to User" event type the  object  include an  array.


### Leasing events

 - [POST LeasingEvents](https://rentengine.redocly.app/openapi/leasing-events/receive-leasing-events.md): Webhook for leasing events (creates, updates, deletes).
Leasing events of the following types are supported:
- "New"
- "Contacted, Awaiting Information"
- "Showing Desired" 
- "Showing Scheduled"
- "Showing Complete"
- "Missed Showing"
- "Ghosting"
- "Application Sent to Prospect"
- "Application Received"
- "Application Pending"
- "Application in Owner Review"
- "Application Approved"
- "Withdrawn"
- "Application Rejected"
- "Prescreen Submitted"
- "Prescreen Rejected - Self reported credit"
- "Prescreen Rejected - Self reported income"
- "Prescreen Rejected - ID Verification"
- "Prescreen Approved"
- "Looking too early"
- "Lease out for signing"
- "Lease Signed"
- "Deposit Received"
- "Move-in Scheduled"
- "Moved In"
- "Unit of Interest Unavailable"
- "Not Interested"
- "Duplicate Lead"
- "Still Deciding"
- "HOA Application Sent To Prospect"
- "HOA Application Submitted"
- "HOA Application Approved"
- "HOA Application Rejected"
- "Showing Failed"
- "Showing Canceled"
- "Showing Confirmed"
- "Arrived for Showing"
- "Showing Started"
- "Log Note"
- "Assign to User"
- "Blocklist Prospect"
- "Unblock Prospect"
- "Reassign Showing"


## Subteams

Operations for managing subteams

### Get subteams

 - [GET /subteams](https://rentengine.redocly.app/openapi/subteams/getsubteams.md): Retrieve subteams with optional filtering and pagination

## Prescreening Templates

Operations for managing prescreening templates used for prospect qualification

### Get prescreening templates

 - [GET /prescreening_templates](https://rentengine.redocly.app/openapi/prescreening-templates/getprescreeningtemplates.md): Retrieve prescreening templates with optional filtering and pagination

## Showings

Operations for managing showing availability and scheduling

### Get unit showing availability

 - [GET /showings/availability](https://rentengine.redocly.app/openapi/showings/getshowingavailability.md): Retrieve showing availability for a specific unit, including available and preferred showing windows

### Create a showing

 - [POST /showings/create](https://rentengine.redocly.app/openapi/showings/createshowing.md): Create a new showing for a unit. This endpoint handles both new showings and rescheduling of existing showings.

## Prospect Types
- : Regular prospect who needs to complete prescreening
- : Real estate agent who needs to provide a valid agent token

## Prescreening
For self prospects, the system will automatically run prescreening based on the unit's prescreen template.
If prescreening fails, the showing will not be created and an appropriate error will be returned.

## Agent Tokens
For agent prospects, a valid 6-character agent token must be provided in the  field.

## Showing Methods
The  field allows specifying the preferred showing method:
- "Accompanied": Agent-guided showing
- "Self Guided": Self-guided showing
- "Remote Guided": Remote-guided showing
- "Remote Guided with Gated Access": Remote-guided showing with gate access