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.
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 oneregistrationNumberRequirements
)
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.
- Request - Maui
- Response
- Request - Miami Beach
- Response
- Request - Boston
- Response
1query {2 districtByCoordinates(3 latitude: 20.7983624 longitude: -156.3319265 locale: "en_US"6 ) {7 id8 description9 nativeLocale10 localizedName11 referenceUrls12 registrationRequired13 legalPropertyTypes {14 type15 subtype16 }17 requirements {18 regulatoryCategory19 regulatoryCategoryLabel20 qualifiedPropertyTypes {21 type22 subtype23 }24 registrationNumberRequirements {25 numberType26 numberTypeLabel27 localName28 format29 regex30 isOptional31 isExpirationDateRequired32 allowPendingRegistrations33 url34 thirdPartyValidation {35 required36 attributes37 }38 }39 additionalDataRequirements {40 key41 keyLocalized42 type43 typeLocalized44 subtype45 subtypeLocalized46 group47 groupLocalized48 isOptional49 }50 minStayNights51 maxNightCap {52 annualLimit53 isEnforced54 }55 exemptions {56 category57 description58 }59 isVacationRental60 }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 British English (en_US). The response shows requirements for hotels and vacation rentals:
- Request
- Response
1query {2 property(id: "368716849", idSource: EXPEDIA)3 {4 coordinates {5 latitude6 longitude7 }8 district(locale: "en_US") {9 id10 description11 nativeLocale12 localizedName13 referenceUrls14 registrationRequired15 legalPropertyTypes {16 type17 subtype18 }19 requirements {20 regulatoryCategory21 regulatoryCategoryLabel22 qualifiedPropertyTypes {23 type24 subtype25 }26 registrationNumberRequirements {27 numberType28 numberTypeLabel29 localName30 format31 regex32 isOptional33 isExpirationDateRequired34 allowPendingRegistrations35 }36 additionalDataRequirements {37 key38 keyLocalized39 type40 typeLocalized41 subtype42 subtypeLocalized43 group44 groupLocalized45 isOptional46 }47 minStayNights48 maxNightCap {49 annualLimit50 isEnforced51 }52 exemptions {53 category54 description55 }56 isVacationRental57 }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
.
- Request
- Response
1{2 property(id: "368716849", idSource: EXPEDIA) {3 id4 ids {5 id6 idSource7 }8 units {9 registration {10 district11 detail {12 compliant {13 status14 reason15 }16 regulatoryCategory17 regulatoryType18 regulatorySubType19 displayRegistrationNumber20 numberOfPhysicalRooms21 }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 theUnitRegistrationDetail
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:
1"requirements": [2 {3 "regulatoryCategory": "BED_AND_BREAKFAST",4 "regulatoryCategoryLabel": "Bed and breakfast",5 "qualifiedPropertyTypes": [6 {7 "type": "bnb",8 "subtype": null9 }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": false21 },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": false31 },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": false41 },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": false51 }52 ],53 "additionalDataRequirements": [],54 "minStayNights": 1,55 "maxNightCap": null,56 "exemptions": null,57 "isVacationRental": false58 },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",11 regulatoryCategory: BED_AND_BREAKFAST,12 registrationRecords: [13 {14 registrationNumber: "HSR12-34567",15 registrationNumberType: PARCEL_NUMBER_TAX_MAP_KEY16 }17 {19 registrationNumberType: GENERAL_EXCISE_TAX_ID20 }21 {23 registrationNumberType: TRANSIENT_ACCOMMODATIONS_TAX_ID24 }25 ]26 }27 ]28 }) {29 complete30 details {31 unitId32 compliant {33 status34 reason35 }36 registrationRecords {37 registrationNumber38 registrationNumberType39 }40 warningStatus {41 description42 code43 }44 }45 }46}
In addition, here is a mutation example and its success, warning, and error response:
- Request
- Response - Success
- Response - Warning
- Response - Error
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 complete21 details {22 unitId23 compliant {24 status25 reason26 }27 registrationRecords {28 registrationNumber29 }30 warningStatus {31 description32 code33 }34 }35 }36}