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.

​

Header

​

Body

​

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

Returned if none of the tenant parameters are provided in the request body

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

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

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