Listing Workflow

Overview

The listing object contains static information of the listing such as basic details, location, description, photos, common facilities, unit types details, check-in/check-out options, etc.

Each listing can have multiple units (e.g. 1 room apartments, 2 room apartments, etc.) and these types are referred to as unit types.

Each unit type can have a description, facilities, maximum number of guests, etc.

Integration Steps

Available Endpoints
GET	`/v1/updates/listings`
GET	`/v1/listings/{listingId}`

Step 1: Fetching the Listing Updates

Make an API call to route GET /v1/updates/listings to fetch the latest listing updates.
As this is a paginated API, you have to pass the following parameters:

Parameter	Description
`cursor`	Each response contains a `next` cursor, that you can then use to retrieve the next page of updates.
`limit`	The maximum number of listing updates returned by API. (Maximum: `50`)

If you are integrating with this API for the first time, the cursor parameter should be omitted. Every subsequent request should contain the cursor that is provided to you in the previous call’s next field. That way you can efficiently poll for listing updates that happened after the last successful pull.

Sample Request

curl -X 'GET' \
  'https://chapi.bookiply.com/v1/updates/listings?cursor=asJ34sgt&limit=3' \
  -H 'Accept: application/json'
  -H 'Authorization: Bearer SIGNED_JWT'

Sample Response

{
  "updates": [
    {
      "listingId": "21e63d96-41aa-471c-af61-965f85e7a22a",
      "listingUrl": "/listings/21e63d96-41aa-471c-af61-965f85e7a22a",
      "active": true,
      "version": "9"
    },
    {
      "listingId": "706b9f81-9c3b-4c1b-8bf9-9ee4489d4b3e",
      "listingUrl": "/listings/706b9f81-9c3b-4c1b-8bf9-9ee4489d4b3e",
      "active": true,
      "version": "11"
    },
    {
      "listingId": "2409f4e5-d4c8-4fda-a1a5-b5d49677191b",
      "listingUrl": "/listings/2409f4e5-d4c8-4fda-a1a5-b5d49677191b",
      "active": true,
      "version": "12"
    }
  ],
  "next": "RyNAJRykNaJRxJSMjIwtNQD1sykxRsjK0M"
}

Parameter	Description
`listingId`	Unique id of the listing
`listingUrl`	The listing URL which can be used to fetch the listing
`active`	Boolean field. `true`- The listing is active and accepts bookings. `false` - The Listing is inactive and does not accept any future bookings
`version`	An unique identifier, specifying the update version in a global incremental series for every update. If the version is 20, this means that this is the 20^thupdate on Listing or Pricing in our inventory

Step 2: Processing the Listing Update

After successfully fetching the listing updates, the content present at the listingUrl field needs to be processed.
The listingUrl field represents the API route for fetching listing content (i.e GET /v1/listings/{listingId}).

Sample Request

curl -X 'GET' \
  'https://chapi.bookiply.com/v1/listings/21e63d96-41aa-471c-af61-965f85e7a22a' \
  -H 'Accept: application/json'
  -H 'Authorization: Bearer SIGNED_JWT'

Sample Response

{
  "listingId": "21e63d96-41aa-471c-af61-965f85e7a22a",
  "location": {
    "lat": 50.9293009,
    "lng": 5.9779776,
    "country": "Germany",
    "city": "Munich",
    "street": "Karlstrasse 66a",
    "postCode": "76133"
  },
  "photos": [
    {
      "id": "PHOTO-1",
      "url": "http://r-ec.bstatic.com/images/hotel/max500/149/14959242.jpg",
      "position": 1,
      "type": "INTERIOR",
      "size": {
        "width": 1920,
        "height": 1080
      },
      "photoTags": [
        "String"
      ]
    }
  ],
  "amenities": [
    {
      "name": "SAUNA",
      "maxCount": 1,
      "privateUsage": true,
      "onDemand": true,
      "extraCostsApply": false
    }
  ],
  "unitTypes": [
    {
      "unitTypeId": "21e63d96-41aa-471c-af61-965f85e7a222",
      "localizations": [
        {
          "language": "en",
          "title": "La Grotta",
          "description": "Die Appartament is located in the center of Bardolino...",
          "arrivalInstructions": "Die Appartamen can be reached by train via ...",
          "crucialInformation": "Pets are not allowed ...",
          "roomsAndAmenities": "The apartment has two rooms with WIFI ...",
          "outdoorArea": "There is a shared pool and a private garden ...",
          "surroundings": "A supermarket is near by ...",
          "additionalInformation": "Cleaning on request for additional fee ..."
        }
      ],
      "details": {
        "maxPersons": 4,
        "category": "STUDIO",
        "sizeInSqm": 100,
        "rooms": {
          "numberOfBedrooms": 2,
          "numberOfLivingrooms": 1,
          "numberOfBathrooms": 2,
          "configuration": [
            {
              "roomId": "room1",
              "roomType": "BED_ROOM",
              "beds": [
                {
                  "type": "BED_SINGLE",
                  "quantity": 1
                }
              ]
            }
          ]
        },
        "rules": {
          "checkInFrom": "11:00",
          "checkInTo": "11:00",
          "checkOutUntil": "11:00",
          "minLeadTime": {
            "duration": 6,
            "unit": "HOURS"
          },
          "freeStayCutoffAge": 2,
          "petsAllowed": true,
          "childrenAllowed": true,
          "babiesAllowed": true,
          "partiesAllowed": true
        },
        "cancellationPolicy": {
          "policyId": "STRICT",
          "gracePeriod": {
            "duration": 2,
            "minCheckInOffset": 14,
            "refundPercent": 100,
            "unit": "DAYS"
          },
          "paymentPolicies": [
            {
              "offset": 10,
              "percentage": 100,
              "referenceDateType": "CHECKIN",
              "unit": "DAYS"
            }
          ],
          "periods": [
            {
              "cutoffTime": "MIDNIGHT_BEFORE_CHECKIN",
              "offset": -30,
              "refundPercent": 50,
              "type": "CHECKIN",
              "unit": "DAYS"
            }
          ]
        }
      },
      "amenities": [
        {
          "name": "LINEN",
          "maxCount": 1,
          "privateUsage": null,
          "onDemand": true,
          "extraCostsApply": true
        }
      ],
      "photos": [
        {
          "id": "PHOTO-1",
          "url": "http://r-ec.bstatic.com/images/hotel/max500/149/14959242.jpg",
          "position": 1,
          "type": "INTERIOR",
          "size": {
            "width": 1920,
            "height": 1080
          },
          "photoTags": [
            "String"
          ]
        }
      ],
      "extraCosts": [
        {
          "typeOfExtraCost": "LINEN",
          "chargeCycle": "PER_PERSON",
          "price": 10,
          "currency": "EUR",
          "type": "MANDATORY",
          "paymentTime": "ON_SITE"
        }
      ],
      "reviews": [
        {
          "reviewId": "REVIEW-1",
          "reviewCreation": "2021-12-23T15:17:59.136Z",
          "arrivalDate": "2022-04-26",
          "headline": "Best Finca in Germany",
          "language": "en",
          "text": "Really nice Finca.",
          "textPositive": "Beautiful Garden. Plenty Sunlight.",
          "textNegative": "There is no tea kettle.",
          "score": 4.2
        }
      ]
    }
  ],
  "details": {
    "storey": 1,
    "sizeOfPlot": 140.5,
    "buildYear": 2001,
    "modernizedYear": 2007,
    "license": "123-456789",
    "classification": "FOUR_STARS",
    "mainResidence": "PRIMARY"
  }
}

Sync Frequency

To have the latest details for the listings, partners should poll the listing updates regularly. The listing updates API can be polled up to the interval provided in the Rate limiting. We recommend polling it at least every minute.