POST
/
listing
curl --location --request POST 'https://api.travtus.com/listings/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
  "amenities": [
    "Swimming Pool",
    "Gym"
  ],
  "features": [
    "Floor heating"
  ],
  "finish": "gold",
  "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
  }
  "bathrooms": [
    {
      "identifier": "listing-1-bathroom-1"
      "has_shower_or_bath": true
      "has_sink": true
      "has_toilet": true
    },
    {
      "identifier": "listing-1-bathroom-2"
      "has_shower_or_bath": false
      "has_sink": true
      "has_toilet": true
    },
  ],
  "bedrooms": 2,
  "description": "A beautiful apartment in the heart of the city.",
  "floorplan_url": "www.floorplans.com/listing-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,
  "lease_terms": [
    {
      "deposit": 1400.00,
      "length_in_months": 12,
      "rent": 700.00
    }
  ],
  "active_date": "2023-01-17",
  "move_in_date": "2023-01-17",
  "sqft": 40.00,
  "tour_url": "www.virtualtours.com/listing-1",
  "unit_number": "1",
  "unit_type": "apartment",
  "listing_url": "www.listings.com/listing-1"
}'

{
  "success": true,
  "listing": [
    {
      "identifier": "listing-1",
      "amenities": [
        "Swimming Pool",
        "Gym"
      ],
      "features": [
        "Floor heating"
      ],
      "finish": "gold",
      "bathrooms": [
        {
          "identifier": "listing-1-bathroom-1"
          "has_shower_or_bath": true
          "has_sink": true
          "has_toilet": true
        },
        {
          "identifier": "listing-1-bathroom-2"
          "has_shower_or_bath": false
          "has_sink": true
          "has_toilet": true
        },
      ],
      "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",
      "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,
      "lease_terms": [
        {
          "identifier": "listing-1-lease-term-1",
          "group": "group-id-1",
          "deposit": 1400.00,
          "length_in_months": 12,
          "rent": 700.00
        }
      ],
      "active_date": "2023-01-17",
      "move_in_date": "2023-01-17",
      "sqft": 40,
      "tour_url": "www.virtualtours.com/listing-1",
      "unit_identifer": "unit-1",
      "unit_number": "1",
      "unit_type": "apartment",
      "listing_url": "www.listings.com/listing-1"
    },
  ]
}
​
Authorization
string
default:"none"
required

The authentication token for your request

​
Body

​
group_id
string
default:"none"
required

The id of a group to use for the listing create/update operation.

Used for:

  • searching for an existing listing record to update
  • setting group assignment for a newly created listing record
​
unit_id
string
default:"none"

The id of the unit you want to associate the newly created or updated listing.

If no unit id is specified, a new unit record will be created instead.

​
amenities
[string]
default:"none"

A list of amenities for the listing to be created or updated.

​
features
[string]
default:"none"

A list of features for the listing to be created or updated.

​
finish
string
default:"none"

The tier of finish for the listing to be created or updated.

​
active_date
date
default:"none"

The date from which the listing should become active.

If this is not provided, it will default ot the current date.

​
address
object
default:"none"

Address information for the listing to be added or updated.

​
bathrooms
[object]
default:"none"

A list of bathroom characteristics for each bathroom for the listing to be updated or created.

​
bedrooms
integer
default:"none"

The number of bedrooms for the listing to be updated or created.

​
description
string

The description of the listing to be updated or created.

​
floorplan_url
string

The url to the floorplan for the listing to be updated or created.

​
image_urls
[string]

A list of urls of images for the listing to be updated or created.

​
is_flex
boolean

Whether the listing to be updated or created is for a flex apartment or not.

​
is_furnished
boolean

Whether the listing to be updated or created is furnished or not.

​
lease_terms
object

A list of the terms for the lease to be updated or created.

​
move_in_date
date

The move in date for the listing to be updated or created.

​
sqft
float

The square feet surface for the listing to be updated or created.

​
tour_url
string

The url to the virtual tour for the listing to be updated or created.

​
unit_number
string

The number of the unit record associated with the listing to be created or updated.

​
unit_type
string
required

The type of the unit associated with the listing to be updated or created.

Will be either apartment or studio_apartment.

​
listing_url
string
required

The url of the listing to be updated or created.

​
Response

​
success
boolean

Whether the listing update or create operation has been successful.

​
listing
object

The listing that has just been created or updated.

​
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 no group id is provided

No group provided for the listing
{
   "error": {
    "type": "no_group_provided",
    "message": "You have not provided a group for the listing."
  }
}

Status Code - 400

Returned if no or wrong unit type is provided

No or wrong unit type provided for the listing
{
   "error": {
    "type": "missing_or_invalid_unit_type",
    "message": "You have not provided a unit type or provided an invalid unit type value for the listing. Please specify a unit type of apartment or studio_apartment."
  }
}

Status Code - 400

Returned if no listing url is provided

No listing url for the listing
{
   "error": {
    "type": "no_listing_url",
    "message": "You have not provided a listing URL for the listing."
  }
}

curl --location --request POST 'https://api.travtus.com/listings/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
  "amenities": [
    "Swimming Pool",
    "Gym"
  ],
  "features": [
    "Floor heating"
  ],
  "finish": "gold",
  "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
  }
  "bathrooms": [
    {
      "identifier": "listing-1-bathroom-1"
      "has_shower_or_bath": true
      "has_sink": true
      "has_toilet": true
    },
    {
      "identifier": "listing-1-bathroom-2"
      "has_shower_or_bath": false
      "has_sink": true
      "has_toilet": true
    },
  ],
  "bedrooms": 2,
  "description": "A beautiful apartment in the heart of the city.",
  "floorplan_url": "www.floorplans.com/listing-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,
  "lease_terms": [
    {
      "deposit": 1400.00,
      "length_in_months": 12,
      "rent": 700.00
    }
  ],
  "active_date": "2023-01-17",
  "move_in_date": "2023-01-17",
  "sqft": 40.00,
  "tour_url": "www.virtualtours.com/listing-1",
  "unit_number": "1",
  "unit_type": "apartment",
  "listing_url": "www.listings.com/listing-1"
}'

{
  "success": true,
  "listing": [
    {
      "identifier": "listing-1",
      "amenities": [
        "Swimming Pool",
        "Gym"
      ],
      "features": [
        "Floor heating"
      ],
      "finish": "gold",
      "bathrooms": [
        {
          "identifier": "listing-1-bathroom-1"
          "has_shower_or_bath": true
          "has_sink": true
          "has_toilet": true
        },
        {
          "identifier": "listing-1-bathroom-2"
          "has_shower_or_bath": false
          "has_sink": true
          "has_toilet": true
        },
      ],
      "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",
      "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,
      "lease_terms": [
        {
          "identifier": "listing-1-lease-term-1",
          "group": "group-id-1",
          "deposit": 1400.00,
          "length_in_months": 12,
          "rent": 700.00
        }
      ],
      "active_date": "2023-01-17",
      "move_in_date": "2023-01-17",
      "sqft": 40,
      "tour_url": "www.virtualtours.com/listing-1",
      "unit_identifer": "unit-1",
      "unit_number": "1",
      "unit_type": "apartment",
      "listing_url": "www.listings.com/listing-1"
    },
  ]
}