Accessibility Scans API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Scan, fix, and verify accessibility issues

Use this flow to check a full site, one page, or an available page collection, then fix and verify the returned issues.

To scan, fix, and verify accessibility issues:

1. Select exactly one scan target:
   • For a full site, specify the full-site scope.
   • For one page, specify its Wix page ID or absolute site URL.
   • For a page collection, call List Accessibility Scan Page Collections and specify the returned collection ID without changing it.
2. Generate one UUID for the intended scan and call Run Accessibility Scan. Reuse that UUID only when retrying the same request.
3. Save the returned scan ID. Poll Get Accessibility Scan after the positive suggestedPollIntervalSeconds delay when the response includes it; otherwise, poll every 5 seconds. Continue while the status is ACCESSIBILITY_SCAN_STATUS_QUEUED or ACCESSIBILITY_SCAN_STATUS_RUNNING.
4. Handle the terminal status:
   • For ACCESSIBILITY_SCAN_STATUS_FAILED, inspect failure, correct the cause, and start a new scan with a new idempotency key.
   • For ACCESSIBILITY_SCAN_STATUS_COMPLETED or ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED, continue to the result methods.
5. Page through List Accessibility Scan Page Summaries. Inspect every page summary. A failed page isn't a clear page.
6. Page through List Accessibility Scan Findings until no next cursor remains. To work on one page or one accessibility concern, specify a page, rule, severity, or category filter. You don't need to query every page separately.
7. For each finding, use its page and element reference, remediation steps, WCAG criteria, and verification steps. For a generated page, use its collection and item IDs with the owning Wix public API. Ask a person before acting when humanInputRequired is true.
8. For a published site, publish the fixes. For an unpublished site, save the fixes.
9. Call Run Accessibility Scan with a new idempotency key and repeat the flow to verify the result.

Handle recoverable run errors as follows:

• For HTTP 429, wait and retry the same intended request with the same idempotency key.
• For SCAN_ALREADY_IN_PROGRESS, poll the returned scan ID.
• For SCAN_STATE_UNKNOWN, retry Get Accessibility Scan with the returned scan ID. Don't start a replacement scan until it reaches a terminal state.
• For IDEMPOTENCY_KEY_REUSED, use a new UUID for the genuinely new scan.
• For SCAN_SIZE_LIMIT_EXCEEDED, use maxPageCount to choose a narrower page or page-collection target.

Reuse a recent scan result

Use this flow when a recent stored result may satisfy the request without starting another scan.

To reuse a recent scan result:

1. Call Get Latest Accessibility Scan with the intended target. If no stored scan is found, start a new scan with a new idempotency key.
2. If the status is ACCESSIBILITY_SCAN_STATUS_QUEUED or ACCESSIBILITY_SCAN_STATUS_RUNNING, poll Get Accessibility Scan after the positive suggestedPollIntervalSeconds delay when the response includes it; otherwise, poll every 5 seconds.
3. If the status is ACCESSIBILITY_SCAN_STATUS_FAILED, inspect failure, correct the cause, and start a new scan with a new idempotency key.
4. For ACCESSIBILITY_SCAN_STATUS_COMPLETED or ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED, check the completion and result-expiration dates.
5. If the result is unexpired and recent enough for the use case, retrieve its page summaries and findings. Otherwise, start a new scan with a new idempotency key.