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

> This endpoint finds listings for the provided 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.

This endpoint only returns vacancies that are active.

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 listings down.

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

You must provide either a group\_id or group\_external\_ref, otherwise the request will fail.

### Header

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

### Body

<ParamField body="group_id" type="string" default="none">
  The id of the group of the listings to retrieve.
</ParamField>

<ParamField body="group_external_ref" type="string" default="none">
  The external reference of the group of the listings to retrieve.
</ParamField>

<ParamField body="external_ref" type="string" default="none">
  The external identifier of the listings to retrieve.
</ParamField>

<ParamField body="identifier" type="string" default="none">
  The internal identifier of the listings to retrieve.
</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="listings" type="[object]">
  The listings retrieved by the endpoint.

  <Expandable title="listing">
    <ResponseField name="identifier" type="string">
      The internal identifier for the retrieved listing.
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      The external identifier for the retrieved listing.
    </ResponseField>

    <ResponseField name="amenities" type="[string]">
      A list of amenities available in the listing's building.
    </ResponseField>

    <ResponseField name="features" type="[string]">
      A list of features for the listing's unit.
    </ResponseField>

    <ResponseField name="finish" type="string">
      The tier of finish for the listing.
    </ResponseField>

    <ResponseField name="bedrooms" type="integer">
      The the number of bedrooms for the listing.
    </ResponseField>

    <ResponseField name="deposit_for_12_month_lease" type="float">
      The deposit amount necessary for a 12 month lease for the listing.
    </ResponseField>

    <ResponseField name="description" type="string">
      The description of the listing.
    </ResponseField>

    <ResponseField name="floorplan_url" type="string">
      The url to the floorplan of the listing.
    </ResponseField>

    <ResponseField name="full_bathrooms" type="integer">
      The number of full bathrooms for the listing (bathrooms including a shower or bath).
    </ResponseField>

    <ResponseField name="half_bathrooms" type="integer">
      The number of half bathrooms for the listing (bathrooms without a shower or bath).
    </ResponseField>

    <ResponseField name="image_urls" type="[string]">
      A list of urls of images for the listing.
    </ResponseField>

    <ResponseField name="is_flex" type="boolean">
      Whether the listing is for a flex apartment or not.
    </ResponseField>

    <ResponseField name="is_furnished" type="boolean">
      Whether the listing is furnished or not.
    </ResponseField>

    <ResponseField name="move_in_date" type="date">
      The move in date for the listing.
    </ResponseField>

    <ResponseField name="rent_for_12_month_lease" type="float">
      The amount of rent per month for a 12 month lease for the listing.
    </ResponseField>

    <ResponseField name="sqft" type="float">
      The square feet surface for the retrieved listing.
    </ResponseField>

    <ResponseField name="tour_url" type="string">
      The url to the virtual tour for the listing.
    </ResponseField>

    <ResponseField name="unit_id" type="string">
      The internal identifier for the unit record associated with the listing.
    </ResponseField>

    <ResponseField name="unit_number" type="string">
      The number of the unit record associated with the listing.
    </ResponseField>

    <ResponseField name="unit_type" type="string">
      The type of unit associated with the listing. Will be either apartment or studio\_apartment.
    </ResponseField>

    <ResponseField name="listing_url" type="string">
      The url of the listing.
    </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 both a group id and group\_external\_ref are provided

```json Both group id and external ref provided for the listing 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 listings operation. Please only provide one of the two."
  }
}
```

Status Code - 400

Returned if neither a group id nor a group\_external\_ref are provided

```json Neither group id nor external ref provided for the listing find operation theme={null}
{
   "error": {
    "type": "no_group_identifier_provided",
    "message": "You have not provided either a group id or a group external reference for the find listings operation. Please provide one of the two."
  }
}
```

Status Code - 401

Returned if the user does not have access to the provided group

```json Authenticated user does not have access to the requested group theme={null}
{
   "error": {
    "type": "no_access_to_group",
    "message": "You do not have access to view information on the group you have provided in the request."
  }
}
```

Status Code - 404

Returned if no listing records can be found matching the provided information.

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

<RequestExample>
  ```bash Example Request theme={null}
  curl --location --request POST 'https://api.travtus.com/listings/find/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <token>' \
  --data-raw '{
    "group_id": "group-id-1"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "last_id": 5,
    "listings": [
      {
        "identifier": "listing-1",
        "external_ref": "listing-external-ref-1",
        "amenities": [
          "Swimming Pool",
          "Gym"
        ],
        "features": [
          "Floor heating"
        ],
        "finish": "gold",
        "bedrooms": 2,
        "deposit_for_12_month_lease": 1400.00,
        "description": "A beautiful apartment in the heart of the city.",
        "floorplan_url": "www.floorplans.com/listing-1",
        "full_bathrooms": 1,
        "half_bathrooms": 1,
        "image_urls": [
          "www.my-images-host.com/listing-1-1.jpg",
          "www.my-images-host.com/listing-1-2.jpg"
        ],
        "is_flex": false,
        "is_furnished": true,
        "move_in_date": "2023-01-17",
        "rent_for_12_month_lease": 700.00,
        "sqft": 40,
        "tour_url": "www.virtualtours.com/listing-1",
        "unit_id": "unit-1",
        "unit_number": "1",
        "unit_type": "apartment",
        "listing_url": "www.listings.com/listing-1"
      },
      {
        "identifier": "listing-2",
        "external_ref": "listing-external-ref-2",
        "amenities": [
          "Swimming Pool",
          "Gym"
        ],
        "features": [
          "Dishwasher"
        ],
        "finish": "Silver",
        "bedrooms": 1,
        "deposit_for_12_month_lease": 1200.00,
        "description": "A beautiful unfurnished studio apartment in the heart of the city.",
        "floorplan_url": "www.floorplans.com/listing-2",
        "full_bathrooms": 1,
        "half_bathrooms": 0,
        "image_urls": [
          "www.my-images-host.com/listing-2-1.jpg",
          "www.my-images-host.com/listing-2-2.jpg"
        ],
        "is_flex": false,
        "is_furnished": false,
        "move_in_date": "2023-01-17",
        "rent_for_12_month_lease": 600.00,
        "sqft": 35,
        "tour_url": "www.virtualtours.com/listing-2",
        "unit_id": "unit-2",
        "unit_number": "2",
        "unit_type": "studio_apartment",
        "listing_url": "www.listings.com/listing-2"
      },
    ]
  }
  ```
</ResponseExample>