Platform API Validation - Real Time

[fionazhou-jsb]

As a STR Platform I want to pass host registration details (registration number, unit number if applicable, street number, and postal code) via API to the STR registry,
so that I can confirm the validity of the registration and ensure compliance with regulations.

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.

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

Presentation

Teams Channel

Document given to Housing regarding API

Business Rules

Real Time API Call:

• [ ] Platform must send the following information per listing at the time creation/publishing, and update of the listing: 
  • registration number 
  • unit number (if applicable)
  • street number 
  • Postal Code 
• [ ] STRR will return response to the platform in real time.
• [ ] If API fails due to API outage, connection/serve issue or any technical reasons, show error message "xxx"
• [ ] If any required information is missing, the validation fails and show a message ""
• [ ] If a registration number cannot be found in the STR registry, the validation fails and show a message ""
• [ ] STRR will check the registration status associated with the registration number first, if the registration status is "Suspended" or "Cancelled", validation fails and show a message "xxx". If the registration status is "Expired", validation fails and show a message "xxx"
• [ ] 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 the following data points are matched.
  • unit number (if applicable)
  • street number 
  • Postal Code 
• [ ] If the registration is "Active" and address matched with the Registry record, inform platform that the validation passes and the listing can be published, created or updated.
• [ ] If the registration is "Active" and address does not match with the Registry record, inform platform that the validation fails and show a message "xxx"
• [ ] Reasonable amount of time to send validation response to the listing and platform. It's very likely that multiple platforms may have multiple listings sending request to Registry for validation.
• [ ] The response for the listing will be stored in the Registry.

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: Registration number is invalid

• Given the platform has sent the registration number and address details to the registry via api,
• When the registration status associated with the registration number is invalid (suspended, cancelled or expired)
• Then the registry will return a failure message indicating that the registration number is invalid.

Scenario 2: Registration number and address details are valid

• Given the platform has sent the registration number and address details to the registry via api,
• When the registration number and address details match the registrar’s records,
• Then the system will return a response confirming that the registration is valid, along with the status, and registration number

Scenario 3: Registration number does not match the address details

• Given the platform has sent the registration number and address details to the registry via the api,
• When the registration number in the registry does not match the provided unit number, street number, or postal code,
• Then the registry will return a failure message indicating that the registration number does not match the address details on file.

Scenario 4: API call fails or external registry is unavailable

• Given the platform is attempting to validate a registration,
• When the external registry is unavailable or the API call fails,
• Then the platform will display an error message informing the user that the validation could not be completed.

[fionazhou-jsb]

@stcepeda for you to review

[mbertucci]

@thorwolpert

Good morning Thor.

We had a brief chat via teams about codes. Can you provide us with recommendations for the codes for this ticket and #23671?

I'm ok with you editing the ticket and adding those numbers or correcting any misunderstandings that we have for the error messages.

Thank you,

M

[stcepeda]

@fionazhou-jsb Registration statuses each need to be separate codes. Active passes validation. Suspended passes validation and requires 1 action from platforms (don't publish but don't cancel bookings), while other statuses require diffrent actions : cancelled (don't publish, cancel bookings), expired (don't publish and I don't remember if they need to cancel bookings). Anyway, each of these need to return a separate code as platform action will vary. Otherwise, looks good.