Scans & Evidence Endpoint
Trigger compliance scans, poll for results, retrieve scan findings, and manage evidence artifacts through the ComplyWise API.
On this page
Scans Overview
The Scans API allows you to trigger on-demand compliance scans, monitor scan progress, and retrieve detailed results. Scans evaluate your connected integrations against the controls in your active compliance frameworks. Each scan produces findings that are mapped to controls and stored as evidence.
- Base path: /api/scans
- Scans run asynchronously — trigger and poll for completion
- Each scan job has a unique UUID for tracking
- Results include pass/fail per control with evidence links
POST /api/scans/trigger
Trigger a new compliance scan. Optionally specify which integrations to include and which framework to evaluate against. If no parameters are provided, all connected integrations are scanned against all active frameworks. Returns a scan job ID for polling.
- Body (optional): { "integration_types": ["aws"], "framework_id": "uuid" }
- Response: { "scan_job_id": "uuid", "status": "queued", "created_at": "..." }
- Omit body to scan all integrations against all frameworks
- Admin and Member roles can trigger scans
GET /api/scans/{scan_job_id}
Check the status of a scan job. Returns the current status (queued, running, completed, failed), start time, completion time, and summary counts for total, passed, and failed controls. Poll this endpoint until status is 'completed' or 'failed'.
- Status values: queued, running, completed, failed
- Response includes: total_controls, passed_controls, failed_controls
- Poll interval recommendation: every 10 seconds
- Completed scans include a summary compliance score
GET /api/scans/{scan_job_id}/results
Retrieve the detailed findings from a completed scan. Returns an array of scan results, each containing the control ID, control title, status (pass/fail/not-applicable), finding details, and evidence reference. Results can be filtered by status or framework.
- Response: array of { "control_id": "...", "status": "pass", "finding": "...", "evidence_key": "..." }
- Filter by status: ?status=fail to see only failing controls
- Filter by framework: ?framework_id=uuid
- Evidence keys reference stored objects for detailed artifacts
Evidence Management
Evidence artifacts are generated automatically from scan results and can also be uploaded manually. The Evidence API allows you to list, retrieve, and upload evidence linked to specific controls and frameworks.
- GET /api/evidence — list all evidence for the tenant, filterable by control_id
- GET /api/evidence/{id} — retrieve a specific evidence artifact with metadata
- POST /api/evidence/upload — upload manual evidence (multipart form with file and metadata)
- Evidence includes: type (auto/manual), created_at, control_id, file reference
Scan History
GET /api/scans — list all scan jobs for the tenant, ordered by creation date. Supports pagination with limit and offset parameters. Use scan history for trend analysis and to track compliance improvements over time.
- Response: paginated array of scan job summaries
- Query params: ?limit=20&offset=0 for pagination
- Each entry includes: id, status, created_at, completed_at, scores
- Historical data retained based on tenant retention policy