Create/Update Listing

This endpoint creates or updates a listing with the provided information.

POST /listing

Example Request

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

Response

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

Header

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.

Show child attributes

building_name · string

The name of the building.

address_line_1 · string · required

The first line of the listing’s address.

address_line_2 · string

The second line of the listing’s address.

city · string

The city of the listing’s address.

country · string

The country of the listing’s address.

state · string · required

The state in which the listing’s address is located.

postal_code · string · required

The postal code of the listing’s address.

latitude · float

The latitude of the listing’s address.

longitude · float

The longitude of the listing’s address.

bathrooms · [object] · default: "none"

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

Show bathroom

has_shower_or_bath · boolean · default: "none"

Does the bathroom have either a shower or a bath?

has_sink · boolean · default: "none"

Does the bathroom have a sink?

has_toilet · boolean · default: "none"

Does the bathroom have a toilet?

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.

Show lease term

deposit · float

The deposit amount for the lease term.

length_in_months · integer

The length in months for the lease term.

rent · float

The rent for the lease term.

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.

Show listing

identifier · string

The internal identifier for the created/updated listing.

amenities · [string]

The list of amenities available in the created/updated listing.

features · [string]

A list of features for the created/updated listing.

finish · string

The tier of finish for the created/updated listing.

bathrooms · [object]

A list of bathroom characteristics for each bathroom of the created/updated listing.

Show bathroom

identifier · boolean

The internal identifier for the bathroom.

has_shower_or_bath · boolean

Does the bathroom have either a shower or a bath?

has_sink · boolean

Does the bathroom have a sink?

has_toilet · boolean

Does the bathroom have a toilet?

bedrooms · integer

The the number of bedrooms for the created/updated listing.

deposit_for_12_month_lease · float

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

description · string

The description of the created/updated listing.

floorplan_url · string

The url to the floorplan of the created/updated listing.

full_bathrooms · integer

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

half_bathrooms · integer

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

image_urls · [string]

A list of urls of images for the created/updated listing.

is_flex · boolean

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

is_furnished · boolean

Whether the created/updated listing is furnished or not.

lease_terms · object

A list of the terms for the created/updated lease.

Show lease term

identifier · string

The identifier of the lease term.

deposit · float

The deposit amount for the lease term.

length_in_months · integer

The length in months for the lease term.

rent · float

The rent for the lease term.

move_in_date · date

The move in date for the created/updated listing.

rent_for_12_month_lease · float

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

sqft · float

The square feet surface for the created/updated listing.

tour_url · string

The url to the virtual tour for the created/updated listing.

unit_id · string

The internal identifier for the unit record associated with the created/updated listing.

unit_number · string

The number of the unit record associated with the created/updated listing.

unit_type · string

The type of unit associated with the created/updated listing.

Will be either apartment or studio_apartment.

listing_url · string

The url of the created/updated 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 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."
  }
}

Example Request

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

Response

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