> ## 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 Tenants

> This endpoint returns a list of tenants filtered with the specified parameters.

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.

### Example use cases

This endpoint allows you to find tenants based on lease parameters.

You can retrieve tenants for a lease with a specific ID.

You can retrieve tenants for all leases within a minimum (`min_move_in_date`) and/or maximum (`max_move_in_date`) move in date range.

You can retrieve tenants for leases belonging specific group via the group's ID.

You can retrieve tenants with a lease at a particular address, with the possibility of narrowing or broadening the search by providing more or less address data.

You can provide either a group id through the `group_id` parameter or a group external reference through the `group_external_ref` attribute to filter the list of retrieved tenants down.

Do not provide both, as this will result in the request failing.

If no group\_id or group\_external\_ref are specified in the request body, the authenticated user will retrieve tenant records for all groups they have access to.

### 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 of a lease to find the tenants for.
</ParamField>

<ParamField body="min_move_in_date" type="string" default="none">
  The lower boundary for the lease's tenants' move in date.
</ParamField>

<ParamField body="max_move_in_date" type="string" default="none">
  The upper boundary for the lease's tenants' move in date.
</ParamField>

<ParamField body="group_id" type="string" default="none">
  The id of the group the lease and tenants belong to.
</ParamField>

<ParamField body="group_external_ref" type="string" default="none">
  The external reference of the group the lease and tenants belong to.
</ParamField>

<ParamField body="address" type="object" default="none">
  The address of a lease to retrieve tenants for.

  <Expandable>
    <ParamField body="building_name" type="string">
      The name of the addresses' building.
    </ParamField>

    <ParamField body="address_line_1" type="string">
      The first line of the address.
    </ParamField>

    <ParamField body="address_line_2" type="string">
      The second line of the address.
    </ParamField>

    <ParamField body="city" type="string">
      The address' city.
    </ParamField>

    <ParamField body="country" type="string">
      The address' country.
    </ParamField>

    <ParamField body="state" type="string">
      The address' state.
    </ParamField>

    <ParamField body="postal_code" type="string">
      The address' postal code.
    </ParamField>

    <ParamField body="latitude" type="float">
      The address' latitude.
    </ParamField>

    <ParamField body="longitude" type="float">
      The address' longitude.
    </ParamField>
  </Expandable>
</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="tenants" type="string">
  A list of the tenants that have been retrieved.

  <Expandable title="properties">
    <ResponseField name="identifier" type="string" default="none">
      The internal identifier for the retrieved tenant.
    </ResponseField>

    <ResponseField name="email_address" type="string">
      The email adddress of the retrieved tenant.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      The first name of the retrieved tenant.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      The last name of the retrieved tenant..
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      An external reference for the retrieved tenant.

      This is typically an identifier you may use for person records in your own system.
    </ResponseField>

    <ResponseField name="phone_number" type="string">
      The phone number of the retrieved tenant.
    </ResponseField>
  </Expandable>
</ResponseField>

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

### 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 both a group id and group\_external\_ref are provided

```json Both group id and external ref provided for the tenant find operation theme={null}
{
   "error": {
    "type": "both_group_identifiers_provided",
    "message": "You have provided both a group id and group external reference for the find tenant operation. Please only provide one of the two."
  }
}
```

Status Code - 404

Returned if no tenant records could not be found.

```json No tenant records found for the provided parameters theme={null}
{
   "error": {
    "type": "not_found",
    "message": "There are no tenant records matching the provided parameters."
  }
}
```

<RequestExample>
  ```bash Request theme={null}
  curl --location --request POST 'https://api.travtus.com/leases/tenants/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <token>' \
  --data-raw '{
      "min_move_in_date": "2020-01-17",
      "identifier": "lease-1"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "tenants": [
      {
        "identifier": "internal-id-1",
        "email_address": "test.tenant.1@travtus.com",
        "first_name": "Test",
        "last_name": "Tenant",
        "external_ref": "id-1",
        "phone_number": "01234567890"
      },
      {
        "identifier": "internal-id-2",
        "email_address": "test.tenant.2@travtus.com",
        "first_name": "Test",
        "last_name": "Tenant 2",
        "external_ref": "id-2",
        "phone_number": "01234567890"
      }
    ],
    "last_id": 5
  }
  ```
</ResponseExample>