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

# Synchronise Listings

> This endpoint synchronises the listings in the given group with the provided listings.

This endpoint allows you to update, create and delete listings for a group.

The endpoint will attempt to reconcile every listing in the request body with an existing one for the given group and update it with the provided details.

If a listing is not found, a new one will be created.

Listings for the provided group that are not included in the request body will be deleted.

If there are no listings passed in the request body, all listings for the provided porfolio will be deleted.

You must provide either a group id via the `group_id` parameter or a group external reference via the `group_external_ref` attribute.

If both are provided, the request will not be successful.

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.

### 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 a group to use for the listing sync operation.

  Used for:

  * searching for an existing listing record to update
  * setting group assignment for a newly created listing record
  * deleting listings in the group that are not provided in the request body

  Please note that you can only pass one of the group\_id and group\_external\_ref. Passing both will return an error.
</ParamField>

<ParamField body="group_external_ref" type="string" default="none">
  The external reference of a group to use for the listing sync operation.

  Used for:

  * searching for an existing listing record to update
  * setting group assignment for a newly created listing record
  * deleting listings in the group that are not provided in the request body

  Please note that you can only pass one of the group\_id and group\_external\_ref. Passing both will return an error.
</ParamField>

<ParamField body="listings" type="[object]" default="none">
  <Expandable title="listing">
    <ParamField body="identifier" type="string" default="none">
      The identifier of the listing you want to update or create.

      This is a unique identifier we have assigned to a listing within our system, which you can retrieve via our find endpoint.
    </ParamField>

    <ParamField body="external_reference" type="string" default="none" required>
      The external reference of the listing you want to update or create.

      This is a unique external reference for a listing that you may set when creating a listing.
    </ParamField>

    <ParamField body="unit_id" type="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.
    </ParamField>

    <ParamField body="amenities" type="[string]" default="none">
      A list of amenities for the listing to be created or updated.
    </ParamField>

    <ParamField body="features" type="[string]" default="none">
      A list of features for the listing to be created or updated.
    </ParamField>

    <ParamField body="finish" type="string" default="none">
      The tier of finish for the listing to be created or updated.
    </ParamField>

    <ParamField body="active_date" type="date" default="none">
      The date from which the listing should become active.

      If this is not provided, it will default ot the current date.
    </ParamField>

    <ParamField body="address" type="object" default="none">
      Address information for the listing to be added or updated.

      <Expandable tilte="address">
        <ParamField body="building_name" type="string">
          The name of the building.
        </ParamField>

        <ParamField body="address_line_1" type="string" required>
          The first line of the listing's address.
        </ParamField>

        <ParamField body="address_line_2" type="string">
          The second line of the listing's address.
        </ParamField>

        <ParamField body="city" type="string">
          The city of the listing's address.
        </ParamField>

        <ParamField body="country" type="string">
          The country of the listing's address.
        </ParamField>

        <ParamField body="state" type="string" required>
          The state in which the listing's address is located.
        </ParamField>

        <ParamField body="postal_code" type="string" required>
          The postal code of the listing's address.
        </ParamField>

        <ParamField body="latitude" type="float">
          The latitude of the listing's address.
        </ParamField>

        <ParamField body="longitude" type="float">
          The longitude of the listing's address.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="bathrooms" type="[object]" default="none">
      A list of bathroom characteristics for each bathroom for the listing to be updated or created.

      <Expandable title="bathroom">
        <ParamField body="has_shower_or_bath" type="boolean" default="none">
          Does the bathroom have either a shower or a bath?
        </ParamField>

        <ParamField body="has_sink" type="boolean" default="none">
          Does the bathroom have a sink?
        </ParamField>

        <ParamField body="has_toilet" type="boolean" default="none">
          Does the bathroom have a toilet?
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="number_of_bathrooms" type="float" default="none">
      The number of bathrooms for this listing.

      Please note that passing both the number\_of\_bathrooms and entries under the bathrooms attribute is not supported and will result in an error being fed back.
    </ParamField>

    <ParamField body="bedrooms" type="integer" default="none">
      The number of bedrooms for the listing to be updated or created.
    </ParamField>

    <ParamField body="description" type="string">
      The description of the listing to be updated or created.
    </ParamField>

    <ParamField body="floorplan_url" type="string">
      The url to the floorplan for the listing to be updated or created.
    </ParamField>

    <ParamField body="image_urls" type="[string]">
      A list of urls of images for the listing to be updated or created.
    </ParamField>

    <ParamField body="is_flex" type="boolean">
      Whether the listing to be updated or created is for a flex apartment or not.
    </ParamField>

    <ParamField body="is_furnished" type="boolean">
      Whether the listing to be updated or created is furnished or not.
    </ParamField>

    <ParamField body="lease_terms" type="object">
      A list of the terms for the lease to be updated or created.

      <Expandable title="lease term">
        <ParamField body="deposit" type="float">
          The deposit amount for the lease term.
        </ParamField>

        <ParamField body="length_in_months" type="integer">
          The length in months for the lease term.
        </ParamField>

        <ParamField body="rent" type="float">
          The rent for the lease term.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="move_in_date" type="date">
      The move in date for the listing to be updated or created.
    </ParamField>

    <ParamField body="sqft" type="float">
      The square feet surface for the listing to be updated or created.
    </ParamField>

    <ParamField body="tour_url" type="string">
      The url to the virtual tour for the listing to be updated or created.
    </ParamField>

    <ParamField body="unit_number" type="string">
      The number of the unit record associated with the listing to be created or updated.
    </ParamField>

    <ParamField body="unit_type" type="string" required>
      The type of the unit associated with the listing to be updated or created.

      Will be either apartment or studio\_apartment.
    </ParamField>

    <ParamField body="listing_url" type="string" required>
      The url of the listing to be updated or created.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the listing sync operation has been successful.
</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 synchronise operation theme={null}
{
   "error": {
    "type": "both_group_identifiers_provided",
    "message": "You have provided both a group id and group external reference for the synchronise listings operation. Please only provide one of the two."
  }
}
```

Status Code - 400

Returned if no group\_id or group\_external\_ref is provided

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

Status Code - 400

Returned if both the number\_of\_bathrooms and the bathrooms attributes are populated

```json Both the number_of_bathrooms and the bathrooms attributes are populated theme={null}
{
   "error": {
    "type": "both_bathroom_attributes_provided",
    "message": "You have provided both a number_of_bathrooms and a bathrooms attribute. Please only 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 the synchronise listings operation for the group you have provided in the request."
  }
}
```

Status Code - 401

Returned if no external reference is provided for one of the listings

```json No external reference provided for a listing theme={null}
{
   "error": {
    "type": "no_external_reference",
    "message": "You have not provided an external reference for a listing. Please provide one."
  }
}
```

Status Code - 401

Returned if any of the dates provided on a listing are in an incorrect format

```json Date on listing is in an incorrect format theme={null}
{
   "error": {
    "type": "date_format_invalid",
    "message": "You have provided a date in an invalid format. All dates must be provided in the YYYY-MM-DD format."
  }
}
```

Status Code - 401

Returned if any of the listings are missing a unit\_type field

```json Vacancy is missing unit_type theme={null}
{
   "error": {
    "type": "missing_unit_type",
    "message": "You are missing the required unit_type field for a listing. Please add the field to your listing."
  }
}
```

Status Code - 401

Returned if any of the listings are missing the listing\_url field

```json Listing is missing listing_url theme={null}
{
   "error": {
    "type": "missing_listing_url",
    "message": "You are missing the required listing_url field for a listing. Please add the field to your listing."
  }
}
```

Status Code - 401

Returned if any of the listings have an invalid unit\_type

```json Listing has invalid unit_type theme={null}
{
   "error": {
    "type": "invalid_unit_type",
    "message": "Invalid value for unit_type field on a listing. Please use either \"apartment\" or \"studio_apartment\"."
  }
}
```

Status Code - 401

Returned if neither of the bathroom attributes are provided

```json Listing has neither of the bathroom attributes provided theme={null}
{
   "error": {
    "type": "no_bathroom_attributes_provided",
    "message": "You have provided neither the number_of_bathrooms or the bathrooms attribute. Please provide one of the two."
  }
}
```

Status Code - 401

Returned if the bathroom attribute is not provided and the number of bathrooms is less than 1

```json Listing does not have a bathroom attribute and the number of bathrooms is less than 1 theme={null}
{
   "error": {
    "type": "invalid_number_of_bathrooms",
    "message": "You have not provided a bathroom attribute and set the number_of_bathrooms to less than 1. Please provide the bathrooms attribute or set the number_of_bathrooms to a number greater than 0."
  }
}
```

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

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true
  }
  ```
</ResponseExample>