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.

​

Header

​

Query Parameters

​

Response

​

Errors

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

Status Code - 400

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

Status Code - 401

{
   "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

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

Status Code - 400

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

Status Code - 400

{
   "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.

{
   "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
    }
  ]
 
}