Find Listings

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

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.

string

default:"none"

required

The authentication token for your request.

Body

string

default:"none"

The id of the group of the listings to retrieve.

string

default:"none"

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

string

default:"none"

The external identifier of the listings to retrieve.

string

default:"none"

The internal identifier of the listings to retrieve.

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

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.

[object]

The listings retrieved by the endpoint.

Show listing

string

The internal identifier for the retrieved listing.

string

The external identifier for the retrieved listing.

[string]

A list of amenities available in the listing’s building.

[string]

A list of features for the listing’s unit.

string

The tier of finish for the listing.

integer

The the number of bedrooms for the listing.

float

The deposit amount necessary for a 12 month lease for the listing.

string

The description of the listing.

string

The url to the floorplan of the listing.

integer

The number of full bathrooms for the listing (bathrooms including a shower or bath).

integer

The number of half bathrooms for the listing (bathrooms without a shower or bath).

[string]

A list of urls of images for the listing.

boolean

Whether the listing is for a flex apartment or not.

boolean

Whether the listing is furnished or not.

date

The move in date for the listing.

float

The amount of rent per month for a 12 month lease for the listing.

float

The square feet surface for the retrieved listing.

string

The url to the virtual tour for the listing.

string

The internal identifier for the unit record associated with the listing.

string

The number of the unit record associated with the listing.

string

The type of unit associated with the listing. Will be either apartment or studio_apartment.

string

The url of the listing.

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

Synchronise Listings

Delete A Listing

⌘I

Introduction

Webhook

Endpoints

Header

Body

Response

Errors

​Header

​Body

​Response

​Errors

Header

Body

Response

Errors