Intro to complianceCopy link

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.

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}