Getting startedCompliance

Intro to compliance

The Lodging Supply GraphQL API provides visibility into regulatory information for jurisdictions where properties will be listed. The goal of the compliance capability is to manage EG regulatory information within software, provide real-time EG regulatory requirements, assist in validating status, and increase operational efficiency. After you have integrated this API, property managers (PMs) can

  • Determine regulatory requirements for a given jurisdiction
  • Retrieve status and details about a unit's (room type's) registration
  • Validate registration status against EG requirements
  • Add or update registration information to a property's unit(s)

The compliance capability is part of the Lodging Supply GraphQL API, which enables connectivity providers to retrieve and manage property and reservation information. All response bodies, including errors, are encoded in JSON. All requests and responses must be made over a secure connection.

If you are unfamiliar with GraphQL concepts, such as queries and mutations, read this overview to learn more.

Download the launch kit here.

Important: Partners must not put Expedia in breach of any privacy or data protection laws. Therefore, to maintain the highest standards of data protection and privacy compliance (such as upholding data minimization, ensuring an appropriate lawful basis is relied upon and robust security measures are in place), we require that partners DO NOT use real personal data under any circumstances during the testing and certification process. Instead, we require partners to use dummy data, fictitious information, or data specifically designated for testing and certification purposes so that no personal data is accessed, shared, and/or reused between partners unnecessarily and unlawfully.

Limitations

Be aware of these as you integrate the compliance capability:

  • This capability is not supported for properties in Japan. In general, the capability is only supported for properties in jurisdictions that are supported by our underlying regulatory service.
  • The capability is not tied to the go-live workflow, which means that non-compliant properties are not automatically delisted at this time.
  • To retrieve or update Vrbo properties, you must specify the supplier ID (external ID). For Expedia properties, specify the Expedia ID.
  • Registration information is updated at the unit level. Updating registration information at the property level is not supported.

Minimum certification requirements

Partners who want to adopt the compliance capability are required to successfully complete end-to-end certification with Expedia Group teams. Specifically, the partner be able to

  • Read regulatory requirements by property ID or by jurisdiction.

  • Read compliance status for each active unit of a property. Note that the query to retrieve a property's registration information at the unit (room type) level will return information for all units, active and inactive. Use the Product API for to identify the correct active unit ID before updating registration information.

  • Add or update each active unit in a jurisdiction with mandatory requirements. Ensure the following is in place:

    • Correct registration information
    • All mandatory regulatory information; for example, some jurisdictions have additional regulatory information (regulatorySubType or more than one registrationNumberRequirements)
  • Include warningStatus in your implementation to ensure that warnings are captured.

  • Implement a synchronization process for properties with mandatory regulatory requirements to capture non-compliant active units and add or update registration on regular basis. Refer to Updating registration information for details.

Retrieving regulatory requirements

You can query for regulatory requirements in two ways:

  • By jurisdiction
  • By property ID

By jurisdiction

Issue the districtByCoordinates query to retrieve a jurisdiction's regulations. This is useful if a PM wants to review requirements before listing properties in a jurisdiction.

These examples retrieve all regulatory information for the specified jurisdiction, such as allowed property types, registration numbers, and minimum and maximum length-of-stay requirements. The responses show requirements for hotels and vacation rentals.

1query {
2 districtByCoordinates(
3 latitude: 20.798362
4 longitude: -156.331926
5 locale: "en_US"
6 ) {
7 id
8 description
9 nativeLocale
10 localizedName
11 referenceUrls
12 registrationRequired
13 legalPropertyTypes {
14 type
15 subtype
16 }
17 requirements {
18 regulatoryCategory
19 regulatoryCategoryLabel
20 qualifiedPropertyTypes {
21 type
22 subtype
23 }
24 registrationNumberRequirements {
25 numberType
26 numberTypeLabel
27 localName
28 format
29 regex
30 isOptional
31 isExpirationDateRequired
32 allowPendingRegistrations
33 url
34 thirdPartyValidation {
35 required
36 attributes
37 }
38 }
39 additionalDataRequirements {
40 key
41 keyLocalized
42 type
43 typeLocalized
44 subtype
45 subtypeLocalized
46 group
47 groupLocalized
48 isOptional
49 }
50 minStayNights
51 maxNightCap {
52 annualLimit
53 isEnforced
54 }
55 exemptions {
56 category
57 description
58 }
59 isVacationRental
60 }
61 }
62}

By property ID

The district query retrieves regulatory requirements at the property level.

This example retrieves all regulatory information in our system for the specified property's jurisdiction, such as allowed property types, registration numbers, and minimum and maximum length-of-stay requirements. The locale argument on district retrieves the results in US English (en_US). The response shows requirements for hotels and vacation rentals:

1query {
2 property(id: "368716849", idSource: EXPEDIA)
3 {
4 coordinates {
5 latitude
6 longitude
7 }
8 district(locale: "en_US") {
9 id
10 description
11 nativeLocale
12 localizedName
13 referenceUrls
14 registrationRequired
15 legalPropertyTypes {
16 type
17 subtype
18 }
19 requirements {
20 regulatoryCategory
21 regulatoryCategoryLabel
22 qualifiedPropertyTypes {
23 type
24 subtype
25 }
26 registrationNumberRequirements {
27 numberType
28 numberTypeLabel
29 localName
30 format
31 regex
32 isOptional
33 isExpirationDateRequired
34 allowPendingRegistrations
35 }
36 additionalDataRequirements {
37 key
38 keyLocalized
39 type
40 typeLocalized
41 subtype
42 subtypeLocalized
43 group
44 groupLocalized
45 isOptional
46 }
47 minStayNights
48 maxNightCap {
49 annualLimit
50 isEnforced
51 }
52 exemptions {
53 category
54 description
55 }
56 isVacationRental
57 }
58 }
59 }
60}

Retrieving a property's registration information and compliance status

Use the registration query to retrieve a property's registration information at the unit (room type) level. This is useful in confirming a unit's information and determining its jurisdiction's requirements. The API returns the registration information in our system for all active and inactive units (room types) on the property.

In the following example, compliant shows whether the unit is compliant and why; include this object and its fields to understand the regulatory status of the unit. Note that the complete field is not included because it reports information at a property level and does not provide the true value for some properties.

Also, be aware that compliance requirements differ by country. For example, in France, it is mandatory for a unit to be assigned regulatorySubType, which is not applicable to Spanish properties (regulatorySubType is null). And the regulatoryCategory value varies across countries and depends on the registrationNumberRequirements.

1{
2 property(id: "368716849", idSource: EXPEDIA) {
3 id
4 ids {
5 id
6 idSource
7 }
8 units {
9 registration {
10 district
11 detail {
12 compliant {
13 status
14 reason
15 }
16 regulatoryCategory
17 regulatoryType
18 regulatorySubType
19 displayRegistrationNumber
20 numberOfPhysicalRooms
21 }
22 }
23 }
24 }
25}

Updating registration information

Use the updateUnitRegistration mutation to update registration information at the room type (unit) level.

  • If an empty or invalid registration number is specified in the mutation, warnings are generated. We strongly recommend that you include warningStatus in your implementation to ensure that you capture warnings if they are generated. warningStatus is a field on the UnitRegistrationDetail object.
  • If the specified room type ID does not belong to the specified property, an error is generated.

To determine the registration requirements to set using the updateUnitRegistration mutation, you must examine the requirements object in the districtByCoordinates or district query’s response. For each regulatory category, review the value of registrationNumberRequirements : isOptional. When isOptional is set to false, you must set registration numbers for those registration number types.

Consider this partial response from the districtByCoordinates query above (for the Maui property):

1"requirements": [
2 {
3 "regulatoryCategory": "BED_AND_BREAKFAST",
4 "regulatoryCategoryLabel": "Bed and breakfast",
5 "qualifiedPropertyTypes": [
6 {
7 "type": "bnb",
8 "subtype": null
9 }
10 ],
11 "registrationNumberRequirements": [
12 {
13 "numberType": "PARCEL_NUMBER_TAX_MAP_KEY",
14 "numberTypeLabel": "Parcel Number (Tax Map Key)",
15 "localName": "Parcel Number (Tax Map Key)",
16 "format": "123456789012 or 1234567890123",
17 "regex": "^[0-9]{12,13}$",
18 "isOptional": false,
19 "isExpirationDateRequired": false,
20 "allowPendingRegistrations": false
21 },
22 {
23 "numberType": "GENERAL_EXCISE_TAX_ID",
24 "numberTypeLabel": "General Excise Tax ID (GET)",
25 "localName": "General Excise Tax ID (GET)",
26 "format": "GE-123-456-7890-01, W12345678-01",
27 "regex": "(^GE-[0-9]{3}-[0-9]{3}-[0-9]{4}-[0-9]{2}$)|(^W[0-9]{8}-[0-9]{2}$)",
28 "isOptional": false,
29 "isExpirationDateRequired": false,
30 "allowPendingRegistrations": false
31 },
32 {
33 "numberType": "REGISTRATION_NUMBER",
34 "numberTypeLabel": "Registration Number",
35 "localName": "Supplemental permit number",
36 "format": null,
37 "regex": "^.{1,20}$",
38 "isOptional": true,
39 "isExpirationDateRequired": false,
40 "allowPendingRegistrations": false
41 },
42 {
43 "numberType": "TRANSIENT_ACCOMMODATIONS_TAX_ID",
44 "numberTypeLabel": "Transient Accomodation Tax ID (TAT)",
45 "localName": "Transient Accomodation Tax ID (TAT)",
46 "format": "TA-123-456-7890-01, W12345678-01",
47 "regex": "(^TA-[0-9]{3}-[0-9]{3}-[0-9]{4}-[0-9]{2}$)|(^W[0-9]{8}-[0-9]{2}$)",
48 "isOptional": false,
49 "isExpirationDateRequired": false,
50 "allowPendingRegistrations": false
51 }
52 ],
53 "additionalDataRequirements": [],
54 "minStayNights": 1,
55 "maxNightCap": null,
56 "exemptions": null,
57 "isVacationRental": false
58 },
59 ...

For the BED_AND_BREAKFAST regulatory category, you must set values for these registration number types (because isOptional is set to false for these):

  • PARCEL_NUMBER_TAX_MAP_KEY
  • GENERAL_EXCISE_TAX_ID
  • TRANSIENT_ACCOMMODATIONS_TAX_ID

The specific requirements for each of these number types is also provided (in format and regex). Here is the mutation to set the registration numbers:

1mutation {
2 updateUnitRegistration(
3 propertyId: "9309956",
4 propertyIdSource: EXPEDIA,
5 forceSave: false,
6 registration: {
7 details: [
8 {
9 unitId: "200299052",
10 regulatoryType: “bnb”,
11 regulatoryCategory: BED_AND_BREAKFAST,
12 registrationRecords: [
13 {
14 registrationNumber: "HSR12-34567",
15 registrationNumberType: PARCEL_NUMBER_TAX_MAP_KEY
16 }
17 {
18 registrationNumber:122334,
19 registrationNumberType: GENERAL_EXCISE_TAX_ID
20 }
21 {
22 registrationNumber: “6P-938373,
23 registrationNumberType: TRANSIENT_ACCOMMODATIONS_TAX_ID
24 }
25 ]
26 }
27 ]
28 }) {
29 complete
30 details {
31 unitId
32 compliant {
33 status
34 reason
35 }
36 registrationRecords {
37 registrationNumber
38 registrationNumberType
39 }
40 warningStatus {
41 description
42 code
43 }
44 }
45 }
46}

Here are additional examples:

1mutation {
2 updateUnitRegistration(
3 propertyId: "9309956",
4 propertyIdSource: EXPEDIA,
5 forceSave: false,
6 registration: {
7 details: [
8 {
9 unitId: "200299052",
10 regulatoryType: "hotel",
11 regulatoryCategory: HOTEL,
12 registrationRecords: [
13 {
14 registrationNumber: "HSR12-34567"
15 }
16 ]
17 }
18 ]
19 }) {
20 complete
21 details {
22 unitId
23 compliant {
24 status
25 reason
26 }
27 registrationRecords {
28 registrationNumber
29 }
30 warningStatus {
31 description
32 code
33 }
34 }
35 }
36}