Skip to main content
GET
/
api
/
v1
/
listing
/
{id}
Get listing by ID
curl --request GET \
  --url https://api.example.com/api/v1/listing/{id} \
  --header 'x-calry-api-key: <api-key>'
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "providerID": "provider-listing-12345",
  "integrationAccountID": "123e4567-e89b-12d3-a456-426614174000",
  "is_tenant_owned": true,
  "name": "Luxury Beach Villa",
  "internalName": "<HOST> Luxury Beach Villa",
  "description": "Beautiful beachfront villa with stunning views",
  "type": "Villa",
  "thumbnailURL": "https://example.com/thumbnail.jpg",
  "pictures": [
    {
      "url": "https://example.com/picture.jpg",
      "description": "A beautiful picture of the listing"
    }
  ],
  "address": {
    "city": "Miami Beach",
    "line1": "123 Ocean Drive",
    "state": "FL",
    "country": "USA",
    "postal_code": "70078"
  },
  "latitude": -80.1918,
  "longitude": 25.7617,
  "minimumNights": 3,
  "maximumNights": 28,
  "maxOccupancy": 10,
  "startPrice": 10,
  "currency": "AED",
  "timeZone": "Asia/Dubai",
  "status": "ACTIVE",
  "rating": {
    "count": 23,
    "average": 4.2
  },
  "bedroomCount": 3,
  "bathroomCount": 3,
  "rooms": {
    "data": [
      {
        "name": "SLEEPING_ALCOVE",
        "count": 1
      },
      {
        "name": "LIVING-DINING_ROOM",
        "count": 1
      }
    ]
  },
  "checkIn": {
    "op": "CHECK_IN",
    "end": "18:00:00",
    "start": "16:00:00"
  },
  "checkOut": {
    "op": "CHECK_IN",
    "end": "15:00:00"
  },
  "houseRules": {},
  "listingDetails": {
    "notes": "",
    "rules": "House rules are NON-negotiable conditions of stay. Any violation of our house rules will result in the immediate cancellation of your reservation, without refund, and your removal from the property.",
    "space": "",
    "access": "",
    "transit": "",
    "interaction": "",
    "instructions": "",
    "neighborhood": ""
  },
  "contact": {
    "name": "John Doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": [
      "[email protected]"
    ],
    "phone": [
      "+1234567890"
    ],
    "address": "123 Main St, Anytown, USA",
    "language": "en",
    "country": "USA"
  },
  "units": 3,
  "parentPropertyID": "<string>",
  "amenities": {
    "categories": {
      "Common Amenities": {
        "categoryID": "common",
        "values": [
          {
            "name": "Wifi",
            "id": "amenity-123"
          },
          {
            "name": "Kitchen",
            "id": "amenity-123"
          },
          {
            "name": "Iron",
            "id": "amenity-123"
          },
          {
            "name": "Pet friendly",
            "id": "amenity-123"
          },
          {
            "name": "Bed linens",
            "id": "amenity-123"
          }
        ]
      },
      "Outdoor": {
        "categoryID": "outdoor",
        "values": [
          {
            "name": "Smoking allowed",
            "id": "amenity-123"
          }
        ]
      }
    }
  },
  "rawAmenities": [
    {
      "id": 3,
      "name": "Wireless"
    },
    {
      "id": 6,
      "name": "Swimming pool"
    },
    {
      "id": 7,
      "name": "Kitchen"
    },
    {
      "id": 13,
      "name": "Washing Machine"
    },
    {
      "id": 30,
      "name": "Shampoo"
    },
    {
      "id": 32,
      "name": "Iron"
    },
    {
      "id": 33,
      "name": "Laptop Friendly workspace"
    },
    {
      "id": 34,
      "name": "TV"
    },
    {
      "id": 36,
      "name": "Smoking allowed"
    },
    {
      "id": 37,
      "name": "Pets allowed"
    },
    {
      "id": 41,
      "name": "Suitable for events"
    }
  ],
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-02T00:00:00.000Z",
  "tags": [
    {
      "id": "a1111111-1111-1111-1111-111111111111",
      "name": "Beachfront"
    },
    {
      "id": "b2222222-2222-2222-2222-222222222222",
      "name": "Pet Friendly"
    }
  ]
}

Authorizations

​
x-calry-api-key
string
header
required

Headers

​
x-calry-tenant-id
string

Optional tenant ID to specify which tenant to operate as. If not provided, the default tenant will be used.

Path Parameters

​
id
string
required

Unique identifier of the listing

Example:

"123e4567-e89b-12d3-a456-426614174000"

Query Parameters

​
displayCurrency
string

Currency code for displaying pricing (ISO 4217)

Example:

"USD"

​
integrationAccountID
string

Filter listings by integration account ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
status
enum<string>

Filter listings by status

Available options:
ACTIVE,
INACTIVE
Example:

"ACTIVE"

​
listingType
enum<string>

Filter by listing source

Available options:
imported,
self
Example:

"imported"

​
guests
number

Minimum number of guests the listing can accommodate

Required range: 1 <= x <= 100
​
bedroomCount
number

Number of bedrooms

Required range: 0 <= x <= 20
​
bathroomCount
number

Number of bathrooms

Required range: 0 <= x <= 20
​
amenities
string[]

Array of amenity IDs to filter by

​
location
string

Location coordinates in format "latitude,longitude"

Example:

"37.7749,-122.4194"

​
radius
number

Search radius in kilometers

Required range: 0.1 <= x <= 100
​
page
number

Page number for pagination

Required range: x >= 1
​
limit
number

Number of items per page

Required range: 1 <= x <= 100

Response

Listing retrieved successfully

​
id
string
required

Unique identifier of the listing

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
providerID
string
required

ID of the listing on the provider system

Example:

"provider-listing-12345"

​
integrationAccountID
string
required

ID of the integration account this listing belongs to

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
is_tenant_owned
boolean
required

Whether the listing is owned by the requesting tenant

Example:

true

​
name
string
required

Name of the listing

Example:

"Luxury Beach Villa"

​
internalName
string
required

Internal name of the listing

Example:

"<HOST> Luxury Beach Villa"

​
description
string
required

Description of the listing

Example:

"Beautiful beachfront villa with stunning views"

​
type
string
required

Type of the property

Example:

"Villa"

​
thumbnailURL
string
required

URL of the thumbnail image of the listing

Example:

"https://example.com/thumbnail.jpg"

​
pictures
object[]
required

List of pictures of the listing

​
address
object
required

Address of the listing

Example:
{
  "city": "Miami Beach",
  "line1": "123 Ocean Drive",
  "state": "FL",
  "country": "USA",
  "postal_code": "70078"
}
​
latitude
number
required

Latitude of the map marker

Example:

-80.1918

​
longitude
number
required

Longitude of the map marker

Example:

25.7617

​
minimumNights
number
required

Minimum Nights

Example:

3

​
maximumNights
number
required

Maximum Nights

Example:

28

​
maxOccupancy
number
required

Maximum Occupancy

Example:

10

​
startPrice
number
required

Start price for listing as set on provider

Example:

10

​
currency
string
required

Currency for displaying prices

Example:

"AED"

​
timeZone
string
required

Timezeone at listing

Example:

"Asia/Dubai"

​
status
enum<string>
required

Status of the listing

Available options:
ACTIVE,
INACTIVE
Example:

"ACTIVE"

​
rating
object
required

Ratings for the property

Example:
{ "count": 23, "average": 4.2 }
​
bedroomCount
number
required

Bedroom count for the listing

Example:

3

​
bathroomCount
number
required

Bathroom count for the listing

Example:

3

​
rooms
object
required

Room information for the listing

Example:
{
  "data": [
    { "name": "SLEEPING_ALCOVE", "count": 1 },
    { "name": "LIVING-DINING_ROOM", "count": 1 }
  ]
}
​
checkIn
object
required

Check-in information for the listing

Example:
{
  "op": "CHECK_IN",
  "end": "18:00:00",
  "start": "16:00:00"
}
​
checkOut
object
required

Check-out information for the listing

Example:
{ "op": "CHECK_IN", "end": "15:00:00" }
​
houseRules
object
required

House rules

​
listingDetails
object
required

Listing Details

Example:
{
  "notes": "",
  "rules": "House rules are NON-negotiable conditions of stay. Any violation of our house rules will result in the immediate cancellation of your reservation, without refund, and your removal from the property.",
  "space": "",
  "access": "",
  "transit": "",
  "interaction": "",
  "instructions": "",
  "neighborhood": ""
}
​
contact
object
required

Contact information for listing

​
units
number
required

Number of units for this type of listing

Example:

3

​
parentPropertyID
string
required

Parent property ID for this listing if it exists. This exists in case current listing is part of a larger listing as a room type

​
amenities
object
required

Mapped amenities available in the listing

Example:
{
  "categories": {
    "Common Amenities": {
      "categoryID": "common",
      "values": [
        { "name": "Wifi", "id": "amenity-123" },
        { "name": "Kitchen", "id": "amenity-123" },
        { "name": "Iron", "id": "amenity-123" },
        {
          "name": "Pet friendly",
          "id": "amenity-123"
        },
        { "name": "Bed linens", "id": "amenity-123" }
      ]
    },
    "Outdoor": {
      "categoryID": "outdoor",
      "values": [
        {
          "name": "Smoking allowed",
          "id": "amenity-123"
        }
      ]
    }
  }
}
​
rawAmenities
array
required

Raw amenities response as received from provider

Example:
[
  { "id": 3, "name": "Wireless" },
  { "id": 6, "name": "Swimming pool" },
  { "id": 7, "name": "Kitchen" },
  { "id": 13, "name": "Washing Machine" },
  { "id": 30, "name": "Shampoo" },
  { "id": 32, "name": "Iron" },
  {
    "id": 33,
    "name": "Laptop Friendly workspace"
  },
  { "id": 34, "name": "TV" },
  { "id": 36, "name": "Smoking allowed" },
  { "id": 37, "name": "Pets allowed" },
  { "id": 41, "name": "Suitable for events" }
]
​
createdAt
string<date-time>
required

Timestamp for listing's creation on Calry

Example:

"2025-01-01T00:00:00.000Z"

​
updatedAt
string<date-time>
required

Timestamp for listing's updation on Calry

Example:

"2025-01-02T00:00:00.000Z"

​
tags
object[]

Tags associated with the listing

Example:
[
  {
    "id": "a1111111-1111-1111-1111-111111111111",
    "name": "Beachfront"
  },
  {
    "id": "b2222222-2222-2222-2222-222222222222",
    "name": "Pet Friendly"
  }
]