Platform API Validation - Bulk

[fionazhou-jsb]

As a STR Platform I want to pass host registration details (registration number, unit number if applicable, street number, postal code and primary listing ID) in bulk via API to the STR registry on a daily basis, So that I can confirm the validity of the registration and ensure compliance with regulations on a daily basis.

Context / Background

Platform must validate their registration details against the Short Term Rental registry. The validation includes checking the registration status and confirming that the address information (unit number, street number, and postal code) entered by the host on the platform site matches what is on file with the registry. Platform needs to do real time validation as well as daily bulk validation.

We need to return a message that indicate whether the validation passes or fails.

It is not clear yet what time platform needs to send the listings in bulk to the registry for daily validation, 11:50pm PST for all platforms or staggered, or as long as every 24 hours window is met.

Presentation

Teams Channel

Document given to Housing regarding API

Business Rules

• [ ] Platform must send the following information for all BC listings once 24 hours to determine the validity of all STR offers appearing on the platform

  • registration number .
  • unit number (if applicable)
  • street number 
  • Postal Code 
  • primary listing ID (where available)

• [ ] Platform will send all the information required in bulk in a format required by the STR Registry.

• [ ] STR Registry will generate the request and send the response to a secure location for the platforms to retrieve.

• [ ] When a response to the daily validation is available, platform will be notified.

• [ ] Reasonable amount of time to send validation response to platform is expected.

• [ ] STR Registry validation will be able to handle a daily validation with over 40-50k records from a platform (i.e., airbnb), as well as from multiple platforms.

• [ ] If API fails due to API outage, connection/serve issue or any technical reasons, show error message "xxx"

• [ ] In the bulk validation, the system will

  • Check the registration status associated with the registration number first,
  • if the registration status is "Suspended", show validation fails and a message "Registration is suspended"
  • if the registration status is "Cancelled", show the validation fails and a message "Registration is cancelled".
  • If the registration status is "Expired", show the validation fails and a message "Registration is expired"

• If the registration status is "Suspended", "Cancelled", "Expired", no need to go through the address match check.

  • If the registration status is "Active", go through the address match check.
  • Address match check will validate if unit number (if applicable), street number, and postal code are matched.
  • If the registration is "Active" and address matched with the Registry record, show the validation passes.
  • If the registration is "Active" and address does not match with the Registry record, show the validation fails and a message "Registration does not match address"
  • For the address to match, the Unit, Address, and Postal Code submitted by the platform must exactly match those same fields within the registry. If a unit number is included in the registry address, the same unit number must be submitted by the Platform to pass validation.
  • If any required information is missing, show the validation fails and a message "xxx" - SUGGEST REMOVING THIS AND JUST USING THE ABOVE "REGISTRATION DOES NOT MATCH ADDRESS", ASSUMING WE MEAN THAT A UNIT NUMBER IS REQUIRED AND MISSING

• [ ] The response for bulk validation will be stored in the Registry. - WHAT DOES THIS MEAN?

• [ ] If a platform does not provide a file for bulk validation every 24 hours, STR Registry should be notified by email. - SHOULD THIS BE A SEPARATE TICKET - TO TRACK PLATFORM REGISTRATIONS?

Bulk Daily API verification 

Platform will request validation for multiple listings.

• listing id 
• registration number
• unit number (if applicable)
• street number 
• Postal Code 

For Valid Registration

- registration: abcd123, code: 404,  status: ACTIVE (suspended, cancelled, expired)  

 - code: 404 means there is an error 

Address mismatch

• registration: dwdw123, code: 1218, description: address mismatch

• code:1218 means it’s passed

Story Scenarios

Scenario 1: Platform sends listing information required in bulk

• Given the platform is required to conduct daily validation with the STR Registry,
• When it's the time to send bulk listings in a file
• Then the platform will send the information (unit number if applicable, street number, postal code and listing ID where applicable) required in bulk via API

Scenario 2: Response is ready

• Given the has processed and checked all the listing information
• When the response is ready to be shared with platform
• Then the system will send a response to a secure location
• And Then the platform will be notified of the response

Scenario 3: API call fails or external registry is unavailable

• Given the platform is attempting to send file for daily bulk validation,
• When the external registry is unavailable or the API call fails,
• Then the platform will view an error message informing the platform that the validation could not be completed.

Scenario 4: Platform missed the deadline to provide the file

• Given the deadline to provide the file is past
• When the platform has not provided a file required
• Then the registry will be notified

[fionazhou-jsb]

@stcepeda for you to review

[stcepeda]

@fionazhou-jsb This looks good. Only comment - I think different error codes are required for the status of the registration. Ie. a different code for active, cancelled, and suspended. Because the platform is required to take different actions for different statuses so it seems like they should all have a unique code?