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.
Date fields should follow a “YYYY-MM-DD” format.
Header
The authentication token for your request
Body
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.
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.
Response
Whether the listing sync operation has been successful.
Errors
Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.
Status Code - 400
{
"error": {
"type": "missing_authorization",
"message": "Your request does not include an 'Authorization' header with a bearer token for your account."
}
}
Status Code - 401
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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."
}
}