> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.travtus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Leases For Tenant

> This endpoint finds leases for a specific tenant based on provided parameters.

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](https://en.wikipedia.org/wiki/ISO_8601).

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

<ParamField header="Authorization" type="string" default="none" required>
  The authentication token for your request
</ParamField>

### Body

<ParamField body="identifier" type="string" default="none">
  The identifier for the tenant to retrieve leases for.
</ParamField>

<ParamField body="external_ref" type="string" default="none">
  The external identifier for the tenant to retrieve leases for.
</ParamField>

<ParamField body="email_address" type="string" default="none">
  The email address for the tenant to retrieve leases for.
</ParamField>

<ParamField body="phone_number" type="string" default="none">
  The phone number for the tenant to retrieve leases for.
</ParamField>

<ParamField body="active" type="boolean" default="false">
  Determines whether only active leases are retrieved for the provided tenant.
</ParamField>

<ParamField body="group_id" type="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.
</ParamField>

<ParamField body="group_external_ref" type="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.
</ParamField>

<ParamField body="after-id" type="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`.
</ParamField>

### Response

<ResponseField name="last_id" type="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.
</ResponseField>

<ResponseField name="leases" type="string">
  A list of the leases that have been retrieved.

  <Expandable title="leases">
    <ResponseField name="identifier" type="string" default="none">
      The identifier for the retrieved lease.
    </ResponseField>

    <ResponseField name="start_date" type="string" default="none">
      The start date of the retrieved lease.
    </ResponseField>

    <ResponseField name="end_date" type="string" default="none">
      The end date of the retrieved lease.
    </ResponseField>

    <ResponseField name="move_in_date" type="string" default="none">
      The move in date of the retrieved lease.
    </ResponseField>

    <ResponseField name="tenants" type="[object]" default="none">
      A list of tenants for the retrieved lease.

      <Expandable title="tenant">
        <ResponseField name="tenant_id" type="string" default="none">
          The id for the tenant associated with the retrieved lease.
        </ResponseField>

        <ResponseField name="tenant_external_ref" type="string" default="none">
          The external reference for the tenant associated with the retrieved lease.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="unit_id" type="string" default="none">
      The id of the unit associated with the retrieved lease.
    </ResponseField>

    <ResponseField name="unit_external_ref" type="string" default="none">
      The external reference of the unit associated with the retrieved lease.
    </ResponseField>

    <ResponseField name="is_furnished" type="boolean" default="none">
      Whether the retrieved lease is for a furnished or unfurnished property.
    </ResponseField>

    <ResponseField name="minimum_days_notice" type="integer" default="none">
      Minimum days of notice that must be given to break the retrieved lease agreement.
    </ResponseField>

    <ResponseField name="deposit" type="float" default="none">
      The deposit amount for the retrieved lease.
    </ResponseField>

    <ResponseField name="rent" type="float" default="none">
      The rent amount for the retrieved lease.
    </ResponseField>

    <ResponseField name="unit_number" type="string" default="none">
      The unit number for the lease's address.
    </ResponseField>

    <ResponseField name="address" type="object" default="none">
      The lease's address.

      <Expandable title="address">
        <ResponseField name="building_name" type="string">
          The name of the building.
        </ResponseField>

        <ResponseField name="address_line_1" type="string">
          The first line of the lease's address.
        </ResponseField>

        <ResponseField name="address_line_2" type="string">
          The second line of the lease's address.
        </ResponseField>

        <ResponseField name="city" type="string">
          The city of the lease's address.
        </ResponseField>

        <ResponseField name="country" type="string">
          The country of the lease's address.
        </ResponseField>

        <ResponseField name="state" type="string">
          The state in which the lease's address is located.
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          The postal code of the lease's address.
        </ResponseField>

        <ResponseField name="latitude" type="float">
          The latitude of the lease's address.
        </ResponseField>

        <ResponseField name="longitude" type="float">
          The longitude of the lease's address.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

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

Status Code - 400

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

Status Code - 401

```json Expired Authorization header bearer token value theme={null}
{
   "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

```json Invalid Authorization header bearer token value theme={null}
{
   "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

```json No tenant information theme={null}
{
   "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

```json Both group id and external ref provided for the find leases for tenant operation theme={null}
{
   "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

```json No group id or group external ref provided for tenant external reference. theme={null}
{
   "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."
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  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": "test@example.com",
      "active": true
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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": "test@example.com",
            "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
        }
      },
    ]
  }
  ```
</ResponseExample>