Skip to content

feat(strr-oas): update strr bulkvalidate description to include e2e flow #274

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jimmypalelil merged 2 commits into from
Aug 20, 2026
+163 −106
Merged

feat(strr-oas): update strr bulkvalidate description to include e2e flow #274

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c66a502
docs(strr): REGBACKLOG-358 update batch validate callback schema with…
jimmypalelil Aug 17, 2026
58ed939
docs(strr): enhance batchValidate specification and integration workflow
jimmypalelil Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
269 changes: 163 additions & 106 deletions web/site/public/strr/platform.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,141 +293,198 @@ paths:
parameters: []
'/permits/:batchValidate':
post:
summary: BatchValidate
responses:
'202':
description: Accepted
'400':
description: Bad Request
'401':
description: Unauthorized
summary: Batch Validate Permits and Addresses
operationId: batch-validate-permit
x-stoplight:
id: pxnr153m69yor
description: Processes a batch submission of permits and/or addresses.
description: |
Asynchronously validates a batch submission of Short-Term Rental (STR) permits and/or checks address exemptions under the *Short-Term Rental Accommodations Act* (STRAA).

### Integration Workflow:
1. **Submit Batch (`POST /permits/:batchValidate`)**:
- Submit up to `50,000` permit or address records in the `data` array.
- Provide `control.count` matching the exact number of items in `data`.
- Provide a secure `control.callBackUrl` (recommended to include a secret token query parameter).
- The API returns `202 Accepted` immediately upon successfully queuing the request.
2. **Receive Completion Webhook**:
- Once processing finishes, STRR dispatches an HTTP `POST` request to your `callBackUrl` with a temporary presigned Google Cloud Storage URL (`fileUrl`).
- Your endpoint must respond with `200 OK` within 10 seconds.
3. **Download Result File**:
- Perform an HTTP `GET` on `fileUrl` (valid for 7 days) to download the batch validation result JSON file.

### Validation Modes per Record in `data`:
- **Permit Verification Mode (with `identifier`, e.g. `H1234567`)**: Validates the permit status (`ACTIVE`, `EXPIRED`, `SUSPENDED`, `CANCELLED`) and matches the submitted unit number, street number, and postal code against official registry records.
- **Address Exemption Mode (without `identifier`, address only)**: Checks provincial data to determine if the address is exempt from registration (`isStraaExempt: true | false`).
parameters:
- $ref: '#/components/parameters/Account-Id'
requestBody:
description: Batch submission payload containing control directives and records to validate.
required: true
content:
application/json:
schema:
type: object
x-examples:
Example 1:
control:
count: 100
callBackUrl: 'http://example.com/jurisdiction/hostsBatch?token=e1231nk123bni12uhi1ub4k2jb3hi2ughri23br'
data:
- identifier: BC1234567
address:
unitNumber: 101a
streetNumber: '101'
streetName: Test Street
postalCode: H0H0H0
city: Test city
- address:
unitNumber: 101a
streetNumber: '101'
streetName: Test Street
postalCode: H0H0H0
city: Test city
required:
- control
- data
properties:
control:
type: object
description: Directives for the submission.
required:
- count
- callBackUrl
properties:
count:
type: integer
description: |-
The total number of records submitted for processing.
Used as a transmission check.
callBackUrl:
type: string
description: An URL to callback and POST the response for long running responses.
data:
type: array
items:
type: object
required:
- address
properties:
identifier:
type: string
description: The registration number of the Permit.
address:
type: object
required:
- streetNumber
- postalCode
properties:
unitNumber:
type: string
description: Unit number must be included if it was included in the Registration.
streetNumber:
type: string
postalCode:
type: string
streetName:
type: string
city:
type: string
$ref: '#/components/schemas/batchValidationRequest'
examples:
Example:
Mixed Batch (Permits & Address Exemptions):
summary: Batch containing permit validations and address exemption checks
value:
control:
count: 2
callBackUrl: 'http://example.com/jurisdiction/hostsBatch?token=e1231nk123bni12uhi1ub4k2jb3hi2ughri23br'
callBackUrl: 'https://platform.example.com/api/v1/strr-callback?token=sec_token_xyz123'
data:
- identifier: H12345678
- identifier: H1234567
address:
unitNumber: 12A
streetNumber: '234'
streetName: Test St
postalCode: H0H0H0
city: Test City
unitNumber: 101A
streetNumber: '101'
streetName: Main St
city: Victoria
province: BC
postalCode: V8V 1A1
- address:
unitNumber: 12A
streetNumber: '234'
streetName: Test St
postalCode: H0H0H0
city: Test City
streetNumber: '721'
streetName: Fort St
city: Victoria
province: BC
postalCode: V8W 1G8
responses:
'202':
description: Batch submission accepted and queued for processing.
content:
application/json:
schema:
type: object
example: {}
'400':
description: Bad Request - Validation or transmission error (e.g. count mismatch, missing control/data).
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorResponse'
examples:
Count Mismatch:
summary: Count does not match number of records
value:
errors:
- code: INVALID_REQUEST
message: Value of 'count' does not match the number of permits submitted for verification.
Missing Control Attributes:
summary: Missing required control attributes
value:
errors:
- code: INVALID_REQUEST
message: "'control' object does not have required attributes."
'401':
description: Unauthorized - Missing or invalid authentication credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorResponse'
'403':
description: Forbidden - Account does not have permission to access batch validation.
content:
application/json:
schema:
$ref: '#/components/schemas/apiErrorResponse'
callbacks:
notification:
batchCompletionNotification:
'{$request.body#/control/callBackUrl}':
post:
summary: Receive single notification about a batch
summary: Receive completion notification with presigned download URL
description: |
Dispatched by STRR upon completion of the batch validation job. Delivers a temporary presigned Google Cloud Storage URL (`fileUrl`) to download the complete batch validation result JSON file.
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- fileUrl
properties:
fileUrl:
type: string
format: uri
description: Temporary presigned URL to download the validation results JSON file. Valid for 7 days.
example: 'https://storage.googleapis.com/strr_bulk_validation_responses_prod/48ad98c4-38ce-426d-bf61-d722fa186f2b?X-Goog-Algorithm=...'
application/json:
schema:
type: object
required:
- fileUrl
properties:
control:
type: object
$ref: '#/components/schemas/control'
data:
type: array
x-stoplight:
id: u3550r8tzkckb
items:
$ref: '#/components/schemas/batchRecord'
fileUrl:
type: string
format: uri
description: Temporary presigned URL to download the validation results JSON file. Valid for 7 days.
example: 'https://storage.googleapis.com/strr_bulk_validation_responses_prod/48ad98c4-38ce-426d-bf61-d722fa186f2b?X-Goog-Algorithm=...'
responses:
'200':
description: Notification successfully processed
description: Notification successfully processed and acknowledged by client endpoint.
content:
text/plain:
examples:
ok:
value: ok
parameters:
- $ref: '#/components/parameters/Account-Id'
parameters: []
components:
schemas:
batchValidationRequest:
title: batchValidationRequest
x-stoplight:
id: batch-val-req-001
description: Request payload for batch validation submission.
type: object
required:
- control
- data
properties:
control:
$ref: '#/components/schemas/control'
data:
type: array
description: Array of permit/address validation items. Maximum 50,000 records per submission.
minItems: 1
items:
type: object
required:
- address
properties:
identifier:
type: string
description: The Short-Term Rental Permit/Registration Number (e.g. H1234567, S1234567, P1234567). If omitted, address exemption is evaluated.
example: H1234567
address:
$ref: '#/components/schemas/address'
batchValidationResultFile:
title: batchValidationResultFile
x-stoplight:
id: batch-val-res-file-001
description: The JSON payload structure downloaded from the presigned fileUrl.
type: object
required:
- control
- data
properties:
control:
$ref: '#/components/schemas/control'
data:
type: array
description: Array of evaluated records with validation statuses, address mismatch errors, or STRAA exemptions.
items:
$ref: '#/components/schemas/batchRecord'
apiErrorResponse:
title: apiErrorResponse
x-stoplight:
id: api-err-resp-001
description: Standard API error response.
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: '#/components/schemas/error'
address:
title: address
description: 'Capture address information for an entity. If the country code is Canada or the US, city and postal code are required.'
Expand Down Expand Up @@ -592,14 +649,14 @@ components:
properties:
code:
type: string
pattern: '^[0-9]*[A-Za-z]?'
example: 101a
example: STREET_NUMBER_MISMATCH
description: Machine-readable error code.
x-stoplight:
id: wbr16i5f71u91
message:
type: string
pattern: '^[0-9]*'
example: '101'
example: Street number does not match with the data in the permit.
description: Human-readable error description.
x-stoplight:
id: vtsqsw0p96lnp
addressRequirements:
Expand Down
Loading