Requirements and best practicesCopy link

This section highlights requirements and best practices to keep in mind when developing your Property API integration.

If you are looking for information about capabilities offered by additional APIs, such as Product API or Image API, refer to the overview page.

Development requirements

Before implementing Property API, make sure you meet these requirements:

• Have a reliable connection to the Internet.
• Be able to initiate HTTPS connections to Expedia Group servers and provide authentication (username/password).
• Expedia will only accept request sent using TLS v1.2 protocol for PCI compliance.
• Be able to connect using the provided Expedia Group URL. Expedia Group does not support connection to the API directly via IP address, as this address is subject to change without notice.
  • If you prefer IP addresses for communication performance reasons, you may consider implementing an address caching strategy to reduce DNS lookups for the URLs.
  • If you whitelist outbound connections, you must do so using a URL pattern rather than an IP range, as Expedia Group cannot guarantee a specific IP range/subnet.
• Be able to generate JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.
• Use Availability and Rates (AR) API to send XML updates about inventory availability.
• Use either Booking Retrieval and Booking Confirmation APIs or Booking Notification API to
  • Be able to retrieve or receive bookings (reservations, modifications and cancellations) using XML messages
  • Be able to provide confirmation numbers for bookings (reservations, modifications, and cancellations) using XML messages
  • Be able to troubleshoot errors according to this specification’s recommendations
• Abide by Expedia Group’s terms and conditions

JSON requirements

The service will return JSON documents for read, create, and update requests, and accept JSON payloads for create and update requests.

In addition:

• Entity - All successful responses returned by Expedia Group services are encapsulated within an HTTP entity. Entities are used to make successful responses generic across different resources and operations. The <Entity> element may represent a single object, or multiple objects. When referring to multiple objects, it is called an array.
• Errors - If a request produces one or more errors, the response will return an array of one or more errors. If errors are present, Entity will not be present.
• MUST-IGNORE - The service is constantly evolving and you should utilize a must-ignore policy. If Property API starts returning additional data elements in responses, you should ignore the data elements you do not need.

Security requirements

Property API uses secure endpoints provided by Expedia Group, https://services.expediapartnercentral.com/. For a complete list of endpoints for different functions within Property API, see the table in Resources and endpoints overview.

Here are the general guidelines for Property API integration:

• The API only supports HTTP 1.1. Requests made with HTTP 1.0 explicitly will be denied.
• TLS 1.2 is required. SSL has been deprecated as a supported protocol and its use is not permitted with integrations to Expedia Group systems. Instead, use TLS to provide over-the-wire encryption (HTTPS). Note that Expedia Group’s servers are not configured to accept posts over unsecured HTTP.
• Be secured using basic authentication. Anyone with development questions or that has not worked with Expedia Group before should contact us.

Minimum certification requirements

To adopt the Property API, you must successfully complete end-to-end certification with Expedia Group teams. Specifically, you must be able to

• Initiate onboarding of a new property and update existing property attributes, images, policies, and fees
• Read (GET) single property details and onboarding status
• Read (GET) property manager-level configurations (only required for non-centralized providers)
• Deactivate (DELETE) a property

Best practices

When designing the electronic interface used to connect to Expedia Group servers to read, create, update, and delete properties, make sure to read and understand the following guidelines, recommendations and best practices.

DO:

• Use Expedia ID or your property IDs to identify correct properties to be updated
• Ensure monitoring is in place in the Property API implementation to validate the success rate of updates, including visibility in error details/messaging.
• Send high-quality images. Three is the minimum, but travelers prefer more!
• Refer to the photo guidelines when selecting images to load on Expedia Group points of sale.

DON’T:

• Send fewer than the minimum required content amenities. Expedia Group Technical Relationship Managers will communicate the minimum number of content amenities. See Set or update property details for more information.
• Send low-resolution images.
• Ignore any errors that might be received. These may signal connection issues or problems with your request.

Alarms and monitoring

Partners should ensure monitoring is in place for their API implementation so they can get detailed information on any errors. Partners should review errors frequently to ensure that the property information is correct, and that all updates are processed accurately. Failure to do so may result in problems with onboarding, taxes, deposits collected on-site, and pricing models.

Get property details and status

Sending a request to /properties/v1/myCompany/myPropertyId will provide a listing of attributes which was most recently submitted to Expedia Group through the Property API.

The response does not represent which attributes are displayed on the website or how it is displayed. The Set Property Details documentation provides a description of attributes that may be moderated or excluded from display.

This presents your view of the property, which can be used by the Property API client to construct an update overlay message. The response does not necessarily show any fields that have been moderated (modified) by Expedia Group, such as star rating, freeform paragraph text, taxes, latitude/longitude coordinates, or address.

You can use the GET property status to determine whether your property creation or updates have been successfully received by Expedia Group using the /properties/v1/mycompany/1234/status endpoint. Because the onboarding process is an asynchronous workflow, the property status endpoint should not be polled more than once per hour to retrieve the most recent status of the property and its assigned Expedia ID.

Detailed examples of both GET property details and GET property status can be found in the Examples.

Set or update property details

This endpoint, https://services.expediapartnercentral.com/properties/v1/{provider name}, may be used to initiate onboarding for new properties or update existing properties. The request body will accept an array containing between 1 and 50 properties per request. Each property must have a unique Provider Property Id.

Content amenities to meet the guidelines for the minimum number of attributes can include any combination from the following categories:

• Internet in public areas and in all-rooms
• Activities and recreation
• Adventure activities
• Water-based activities
• Safari and wildlife
• Fitness
• Recreation
• Breakfast details and dining
• Pool and pool amenities
• Children and family-friendly features
• Business features and amenities
• Guest services
• Parking and transportation amenities
• Outdoor areas and amenities
• Property specifics
• Property design
• All-room amenities
• Front desk details, instructions for self check-in, minimum check-in age, and check-out time (under Policies)

Codes for closures, renovations, mandatory or optional fees do not contribute to the total number of amenities for the purposes of these guidelines.

For a detailed example, see Set or update property details in the Request section.

Make sure minimum requirements are met

Here are the minimum requirements for a property to go live:

Update a property by Expedia Property ID

After onboarding, many of the attributes submitted during onboarding can be updated by sending a full overlay update to the Property API. After the initial onboarding, some updates, such as latitude/longitude, will be accepted by the Property API but not processed. See the Set or Update Property Details article and detailed documentation for a listing of attributes that are not updatable via the Property API.

Updating a property that is already onboarded is a similar operation to the original onboarding - a full overlay of a single property is required. It is recommended that you GET (by Expedia ID) the property details first, modify the fields that you'd like to change (and/or add new), then send the entire JSON document as a PUT request to update the property. The full overlay must include images as well.

Example: If there are 10 images loaded via Property API and then another PUT was sent with 4 Images, then 6 images would be removed. If an overlay is sent with an empty image array in the PUT, then all 10 will be removed. To ensure images are not removed, partners should trigger a GET by Expedia ID prior to the update and ensure the images piece is retained in the update. Partners may find the functionality of Image API easier for image management if properties often update content or images.

Also note that Property API will NOT remove images loaded with Image API or manually loaded in Partner Central. Property API updates should only deactivate images loaded with Property API and only when the partner has requested that change by specifying a subset of images of what was originally sent, as in the example above.

Send high quality images

We recommend all partners to abide by the Expedia Group standards for images to ensure good content:

• Photo Quantity: Expedia Group recommends providing travelers with photos that showcase different aspects of the property, including:
• 4 or more photos for each room type and 1 photo of the bathroom
• 1 exterior photo
• 1 entrance/lobby photo
• 1 photo per key amenity (for example: pool, fitness center, recreation activities) Expedia Group recommends providing travelers with photos that showcase different aspects of the property, including:
• 4 or more photos for each room type and 1 photo of the bathroom
• 1 exterior photo
• 1 entrance/lobby photo
• 1 photo per key amenity (for example: pool, fitness center, recreation activities)
• You must send a minimum of 3 images per property. For better conversion to bookable units, Expedia Group suggests sending at least 20 property photos.
• Photo Quality: Photos should be high resolution, or 2,880 pixels or higher on the longest edge, with a maximum file size of 15 MB. Photos must be in one of the following file formats:
• JPG, PNG, and BMP

Property API does not send error messages when an image is rejected. To find out what images are currently associated with a property, use Image API or the GET by Expedia ID functionality.

You are not required to load various sizes of the same image. You should load the highest possible resolution for each image and Expedia Group will then produce all required derivatives to make the image experience optimal across all features and points of sale.

Photos may be rejected if the image includes any of the following:

• Text or graphic overlays
• Borders
• Inappropriate material (nudity, adult themes, etc.)
• Close-up
• Logos, maps, floor plans, or illustrations
• Montage or collage
• Black and white or sepia
• Blurry or pixelated

To upload images with Property API or Image API, you must have your images hosted on an HTTP/HTTPS site or at an Amazon Web Services (AWS) location. Expedia Group cannot currently accept other types of locations like FTP or SFTP. Those wishing to push files need to use Partner Central to do so.

Transfer image management from Property API to Image API

Expedia Group recommends that Image API should always be used to load images if resources are available to code to it. Image API supports associating images to specific room types, which can help convert customer views into bookings.

If the reason for adopting Image API is to completely discontinue sending images with Property API, then control of the images needs to be converted to Image API.

Do so with the following steps:

1. GET the property details with PropertyAPI.
2. Send a PUT update (full overlay) including all existing content, but with empty image arrays via Property API. This will deactivate these images in the Expedia Group system.
3. Send the images with a create (POST) in Image API. This will fully transfer image control of those images to Image API.

If steps 1 and 2 are skipped, and only step step 3 is completed, the images will be flagged as duplicates. If an update (PATCH) of the images originally created via Property API using Image API is attempted, the creator of the images is still Property API in Expedia Group’s system. Thus, any subsequent content updates with an empty image array using Property API would delete these images again.

Deactivate/delete a property

Sending a DELETE request for an onboarded property will deactivate the property in Expedia Group's system. Content will not be deleted. The property's state will be changed to inactive. The property can later be re-enabled using the Set Property Details API call. A success response to the delete request will be a 200/OK and the response will echo back the details of the property which was just deleted.

For a detailed example, see the Property resources.

Billing setup

Property API supports two scenarios:

1) Connectivity providers that can centrally handle billing and payments for their associated properties. For Expedia Collect bookings, this would require that the API partner uploads consolidated invoices via Partner Central for any properties onboarded with Property API, and to be able to receive payment centrally for the net rates being invoiced for. Similarly for Hotel Collect bookings, they would be required to work with a centralized account for consolidated commission payments.

2) Decentralized billing is also supported. This means a connectivity provider can onboard multiple property managers on their behalf and Expedia can maintain financial relationships directly at the property manager level. Sample Onboarding RQ for Decentralized billing Onboarding can be found here.

Property ownership transfer

If you are taking over a property that was already onboarded onto the Expedia Group platform either by another provider or through a manual onboarding method, we recommend the actions below be performed (in the order specified) to seamlessly utilize Property API on this property to manage content and shell data:

1. Ensure that the property has switched providers and is connected to you. Properties can do so with the self-service option in Partner Central (under the Room and Rates tab).
2. Perform a GET by ExpediaID on the property: This will return all relevant data about the property as it is stored in Expedia Group’s system. It is always recommended to use the GET by Expedia ID because it provides the latest information about the property as it is stored on our platform. If the property was onboarded through another partner, the GET by Expedia ID response would reveal the 'providerPropertyId' registered by the previous partner. If the property was onboarded previously via a manual onboarding method, then no provider Property Id will be returned.
3. Perform anUpdate (PUT) by Expedia ID: In this PUT message, include and update the provider Property Id for the property to the ID you use in your platform/system. This will update the ID to the 'providerPropertyId' you have provided.

The property is now ready to be managed for content or shell updates with Property API using either the "Update by Expedia ID" or the "Update by Provider Property ID" that the API supports.