Find Leases

You need to provide at least one search parameter in your request to find leases. All date fields included in the query parameters need to be specified as ISO8601-formatted date strings. Date fields should follow a “YYYY-MM-DD” format.

Example use cases

This endpoint allows you to find leases based on a number of parameters. You can retrieve all leases for a given group or list of groups by providing their IDs. You can retrieve all leases for a specific unit by passing the internal ID or the external reference. You can retrieve leases for a given address, with the possibility of narrowing or broadening the search by providing more or less address data. You can provide either group ids through the group_ids parameter or group external references through the group_external_refs attribute to filter the list of retrieved leases down. Do not provide both, as this will result in the request failing. If no group_ids or group_external_refs are specified in the request, the authenticated user will retrieve lease records for all groups they have access to.

Authorization

string

default:"none"

required

The authentication token for your request

Query Parameters

identifier

string

default:"none"

The identifier for the leases to be retrieved.

start_date

string

default:"none"

The start date of the leases to be retrieved.

end_date

string

default:"none"

The end date of the leases to be retrieved.

move_in_date

string

default:"none"

The move in date of the leases to be retrieved.

group_ids

string

default:"none"

A comma-separated list of group ids to retrieve leases for.

group_external_refs

string

default:"none"

A comma-separated list of group external refs to retrieve leases for.

unit_external_ref

string

default:"none"

The unit external reference to retrieve leases for.

unit_identifier

string

default:"none"

The unit internal ID to retrieve leases for.

address

object

default:"none"

An address to retrieve leases for.

Show child attributes

building_name

string

The name of the addresses’ building.

address_line_1

string

The first line of the address.

address_line_2

string

The second line of the address.

city

string

The address’ city.

country

string

The address’ country.

state

string

The address’ state.

postal_code

string

The address’ postal code.

latitude

float

The address’ latitude.

longitude

float

The address’ longitude.

after_id

string

default:"none"

The API returns a maximum of 100 records per call.You can use this parameter to load the next set of records by passing in the value returned in the response, under pagination.next_cursor.

offset

integer

default:"0"

Number of records to skip before returning results.

limit

integer

default:"100"

Maximum number of records to return per page.

Response

data

array

A list of the leases that have been retrieved.

Show lease object

identifier

string

default:"none"

The identifier of the retrieved lease.

start_date

string

default:"none"

The start date of the retrieved lease.

end_date

string

default:"none"

The end date of the retrieved lease.

move_in_date

string

default:"none"

The move in date of the retrieved lease.

landlord_id

string

default:"none"

The id of the landlord of the retrieved lease.

tenants

[object]

default:"none"

A list of tenants for the retrieved lease.

Show tenant

tenant_id

string

default:"none"

The id for the tenant associated with the retrieved lease.

tenant_external_ref

string

default:"none"

The external reference for the tenant associated with the retrieved lease.

unit_id

string

default:"none"

The id of the unit associated with the retrieved lease.

unit_external_reference

string

default:"none"

The external reference of the unit associated with the retrieved lease.

address

object

The address of the retrieved lease.

Show address

building_name

string

The name of the addresses’ building.

address_line_1

string

The first line of the address.

address_line_2

string

The second line of the address.

city

string

The address’ city.

country

string

The address’ country.

state

string

The address’ state.

postal_code

string

The address’ postal code.

latitude

float

The address’ latitude.

longitude

float

The address’ longitude.

is_furnished

boolean

default:"none"

Whether the retrieved lease is for a furnished or unfurnished property.

minimum_days_notice

integer

default:"none"

Minimum days of notice that must be given to break the retrieved lease agreement.

deposit

float

default:"none"

The deposit amount for the retrieved lease.

rent

float

default:"none"

The rent amount for the retrieved lease.

pagination

object

Pagination information for navigating through the result set.

Show pagination

count

integer

Total number of items matching the query.

next_cursor

string

The cursor to use in the after_id parameter to get the next page of results. Will be null if there are no more pages.

previous_cursor

string

The cursor to use in the after_id parameter to get the previous page of results. Will be null if this is the first page.

Errors

Listed below are common errors that may be returned by the endpoint, along with their corresponding status code. Status Code - 400

Missing Authorization header

{
   "error": {
    "type": "missing_authorization",
    "message": "Your request does not include an 'Authorization' header with a bearer token for your account."
  }
}

Status Code - 401

Expired Authorization header bearer token value

{
   "error": {
    "type": "expired_token",
    "message": "The bearer token you have provided in the 'Authorization' header has expired. Please obtain a new one."
  }
}

Status Code - 401

Invalid Authorization header bearer token value

{
   "error": {
    "type": "invalid_authorization",
    "message": "The bearer token you have provided in the 'Authorization' header is invalid."
  }
}

Status Code - 400

No search parameters provided

{
   "error": {
    "type": "no_search_parameters",
    "message": "At least one search parameter is required to find leases."
  }
}

Status Code - 400

Both group id and external ref provided for the tenant find operation

{
   "error": {
    "type": "both_group_identifiers_provided",
    "message": "You have provided both a group id and group external reference for the find leases operation. Please only provide one of the two."
  }
}

Status Code - 404 Returned if no lease records could not be found.

No lease records found for the provided parameters

{
   "error": {
    "type": "not_found",
    "message": "There are no lease records matching the provided parameters."
  }
}

curl --location --request GET 'https://api.travtus.com/leases/?start_date=2023-01-17' \
--header 'Authorization: bearer <token>'

{
  "leases": [
    {
      "identifier": "lease-1",
      "start_date": "2023-01-17",
      "end_date": "2023-12-17",
      "move_in_date": "2023-01-17",
      "landlord_id": "landlord-id-1",
      "tenants": [
        {
          "tenant_id": "tenant-id-1",
          "tenant_external_ref": "tenant-external-ref-1"
        }
      ],
      "unit_id": "unit-id-1",
      "unit_external_ref": "unit-external-ref-1",
      "is_furnished": false,
      "minimum_days_notice": 30,
      "deposit": 1400.0,
      "rent": 700.0
    },
    {
      "identifier": "lease-2",
      "start_date": "2023-01-17",
      "end_date": "2023-12-17",
      "move_in_date": "2023-01-17",
      "landlord_id": "landlord-id-1",
      "tenants": [
        {
          "tenant_id": "tenant-id-2",
          "tenant_external_ref": "tenant-external-ref-2"
        },
        {
          "tenant_id": "tenant-id-3",
          "tenant_external_ref": "tenant-external-ref-3"
        }
      ],
      "unit_id": "unit-id-2",
      "unit_external_ref": "unit-external-ref-2",
      "is_furnished": true,
      "minimum_days_notice": 30,
      "deposit": 1600.0,
      "rent": 800.0
    }
  ]
 
}

Introduction

Deployment Guide

Travtus API & Webhook

Miscellaneous

Glossary

Example use cases

Header

Query Parameters

Response

Errors

Introduction

Deployment Guide

Travtus API & Webhook

Miscellaneous

Glossary

​Example use cases

​Header

​Query Parameters

​Response

​Errors

Example use cases

Header

Query Parameters

Response

Errors