Find Leases For Tenant

The endpoint will automatically match the tenant information provided with an existing tenant within the system. At least one of the following tenant identifiers need to be provided:

Internal tenant identifier (identifier)
External tenant identifier (external_ref) and the group id the tenant belongs to (group)
The email address of the tenant (email_address)
The phone number of the tenant (phone_number)

If no tenant match is retrieved, an empty set of leases will be returned. Active leases have an end date in the future and a start date in the past relative to the current date. All date fields included in the body parameters need to be specified as ISO8601-formatted date strings. Date fields should follow a “YYYY-MM-DD” format. If finding tenants via their external referance, you must provide the group the tenant belongs to. The group can be specified via either the group_id or group_external_ref attribute. Do not provide both, as this will result in the request failing.

Example use cases

This endpoint allows you to find leases for a specific tenant. You can retrieve all leases for a tenant given their internal id or external reference and group id. You can retrieve all leases for a tenant given their phone number or email address.

Authorization

string

default:"none"

required

The authentication token for your request

Body

identifier

string

default:"none"

The identifier for the tenant to retrieve leases for.

external_ref

string

default:"none"

The external identifier for the tenant to retrieve leases for.

email_address

string

default:"none"

The email address for the tenant to retrieve leases for.

phone_number

string

default:"none"

The phone number for the tenant to retrieve leases for.

active

boolean

default:"false"

Determines whether only active leases are retrieved for the provided tenant.

group_id

string

default:"none"

The id of the group the tenant belongs to.This attribute or the group_external_ref one is needed if using the external_ref for the tenant.

group_external_ref

string

default:"none"

The external reference of the group the tenant belongs to.This attribute or the group_id one is needed if using the external_ref for the tenant.

after-id

string

default:"1"

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

Response

last_id

integer

The last id in the set of results returned for this API call.You can use this value in the after-id parameter to load the next set of results.If there are no more results to load, this value will be -1.

leases

string

A list of the leases that have been retrieved.

Show leases

identifier

string

default:"none"

The identifier for 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.

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_ref

string

default:"none"

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

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.

unit_number

string

default:"none"

The unit number for the lease’s address.

address

object

default:"none"

The lease’s address.

Show address

building_name

string

The name of the building.

address_line_1

string

The first line of the lease’s address.

address_line_2

string

The second line of the lease’s address.

city

string

The city of the lease’s address.

country

string

The country of the lease’s address.

state

string

The state in which the lease’s address is located.

postal_code

string

The postal code of the lease’s address.

latitude

float

The latitude of the lease’s address.

longitude

float

The longitude of the lease’s address.

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 Returned if none of the tenant parameters are provided in the request body

No tenant information

{
   "error": {
    "type": "no_tenant_information",
    "message": "You need to provide at least one of identifier, external_ref AND group, email_address, or phone_number in the request body."
  }
}

Status Code - 400 Returned if both of the group_id and group_external_ref attributes are provided

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

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

Status Code - 400 Returned if no group_id or group_external_ref is provdided when identifying a tenant via an external_ref

No group id or group external ref provided for tenant external reference.

{
   "error": {
    "type": "both_group_identifiers_provided",
    "message": "You have not a group id or group external reference when identifying a tenant via their external reference. Please provide one of the two."
  }
}

curl --location --request POST 'https://api.travtus.com/leases/find-for-tenant/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
    "email_address": "[email protected]",
    "active": true
}'

{
  "leases": [
    {
      "identifier": "lease-1",
      "start_date": "2023-01-17",
      "end_date": "2023-12-17",
      "move_in_date": "2023-01-17",
      "tenants": [
        {
          "identifier": "0123-4567-8901-2345",
          "external_ref": "person-external-ref-1",
          "email_address": "[email protected]",
          "phone_number": "01234567890",
          "active": true,
          "group": "group-1"
        }
      ]
      "unit_id": "unit-id-1",
      "unit_external_ref": "unit-id-1",
      "is_furnished": false,
      "minimum_days_notice": 30,
      "deposit": 1400.0,
      "rent": 700.0,
      "unit_number": "1",
      "address": {
        "building_name": "Building 1",
        "address_line_1": "Blvd Street",
        "address_line_2": "Appartment 12",
        "city": "New York",
        "country": "United States",
        "state": "New York",
        "postal_code": "10001",
        "latitude": 40.730610,
        "longitude": -73.935242
      }
    },
  ]
}

Introduction

Webhook

Endpoints

Find Leases For Tenant

Example use cases

Header

Body

Response

Errors

Introduction

Webhook

Endpoints

Documentation Index

​Example use cases

​Header

​Body

​Response

​Errors

Example use cases

Header

Body

Response

Errors