GET
/
leases
/
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
    }
  ]
 
}

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.

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

​
pagination
object

Pagination information for navigating through the result set.

​
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
    }
  ]
 
}