POST
/
listings
/
find
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"
}'

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

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.

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.

​
Authorization
string
default:"none"
required

The authentication token for your request.

​
Body

​
group_id
string
default:"none"

The id of the group of the listings to retrieve.

​
group_external_ref
string
default:"none"

The external reference of the group of the listings to retrieve.

​
external_ref
string
default:"none"

The external identifier of the listings to retrieve.

​
identifier
string
default:"none"

The internal identifier of the listings to retrieve.

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

​
listings
[object]

The listings retrieved by the endpoint.

​
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 both a group id and group_external_ref are provided

Both group id and external ref provided for the listing find operation
{
   "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

Neither group id nor external ref provided for the listing find operation
{
   "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

Authenticated user does not have access to the requested group
{
   "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.

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

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"
}'

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