Skip to main content
POST
/
api
/
scan
/
run
Run Scan
curl --request POST \
  --url https://api.example.com/api/scan/run \
  --header 'Content-Type: application/json' \
  --data '
{
  "policy_id": "<string>",
  "upload_id": "<string>",
  "mapping_id": "<string>",
  "audit_id": "<string>",
  "audit_name": "<string>"
}
'
{
  "scan_id": "<string>",
  "status": "<string>"
}

​
Overview

Initiates a compliance scan by executing policy rules against uploaded financial data. The scan runs synchronously and processes up to 50,000 records, identifying violations and calculating a compliance score.

​
Request Body

​
policy_id
string
required
The ID of the compliance policy containing the rules to execute
​
upload_id
string
required
The ID of the uploaded data file to scan. Must reference a valid upload from /api/upload
​
mapping_id
string
required
The ID of the column mapping configuration. Must be confirmed via /api/mapping/confirm before scanning
​
audit_id
string
Optional audit identifier for grouping related scans
​
audit_name
string
Optional human-readable name for the audit

​
Response

​
scan_id
string
required
Unique identifier for the created scan. Use this to poll scan status via /api/scan/{id}
​
status
string
required
Initial scan status. Always returns "running" even though the scan completes synchronously

​
Example Request

{
  "policy_id": "550e8400-e29b-41d4-a716-446655440000",
  "upload_id": "123e4567-e89b-12d3-a456-426614174000",
  "mapping_id": "789e0123-e45b-67c8-d901-234567890123",
  "audit_name": "Q1 2024 Compliance Audit"
}

​
Example Response

{
  "scan_id": "abc12345-def6-7890-ghij-klmnopqrstuv",
  "status": "running"
}

​
Error Responses

​
400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid request body",
  "details": [
    {
      "path": ["policy_id"],
      "message": "Required"
    }
  ]
}

​
404 Not Found - Missing Mapping

{
  "error": "NOT_FOUND",
  "message": "Mapping not found. Confirm mapping first."
}

​
404 Not Found - Missing Upload

{
  "error": "NOT_FOUND",
  "message": "Upload not found. Upload data first."
}

​
404 Not Found - No Rules

{
  "error": "NOT_FOUND",
  "message": "No rules found for this policy."
}

​
Scan Process

The endpoint performs the following operations:
  1. Validates Request - Ensures all required parameters are present and valid
  2. Retrieves Resources - Fetches mapping configuration, uploaded data, and active policy rules
  3. Creates Scan Record - Initializes a scan record in the database with status: "running"
  4. Executes Rules - Runs all active rules against the data using the RuleExecutor engine
  5. Calculates Score - Computes compliance score based on violations and severity
  6. Persists Violations - Saves detected violations in batches (2,500 per batch, 5 concurrent batches)
  7. Updates Status - Marks scan as completed with final metrics
  8. Links PII Findings - Associates any PII findings from the upload with this scan

​
Performance

  • Processes up to 50,000 records per scan
  • Typical execution time: < 5 seconds for large datasets
  • Uses concurrent batching for violation persistence (5 parallel batches)

Build docs developers (and LLMs) love

Get started for freeTalk to us