POST
/
leases
/
find-for-tenant
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
      }
    },
  ]
}

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.

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