Verifications API

The Verifications API enables you to manage the vulnerability retest and verification workflow. After vulnerabilities are remediated, verifications track whether fixes are successful.

Authentication

All endpoints require the FACTION-API-KEY header. Remediation or Assessor permissions are required for most operations.

Get All Verifications

Requires Remediation permission

Retrieve all verifications in the system, optionally filtered by date range.

POST /api/verifications/all

Request Parameters

FACTION-API-KEY

string

required

API authentication key

start

date

Filter by assessor completed date range start (format: YYYY-MM-DD)

end

date

Filter by assessor completed date range end (format: YYYY-MM-DD)

Response

Returns all open verifications and completed verifications within the specified date range. Non-completed verifications are returned regardless of date range.

long

Vulnerability ID

VerificationId

long

Unique verification identifier

Start

timestamp

Verification start date (milliseconds)

End

timestamp

Verification end date (milliseconds)

AppId

string

Application identifier

AssessmentName

string

Assessment name

Tracking

string

Vulnerability tracking ID (e.g., VID-1234)

Status

string

Verification status: “In Progress”, “Passed”, or “Failed”

WorkFlowStatus

integer

Internal workflow status code

Completed

timestamp

Assessor completion date (milliseconds, empty if in progress)

RemediationCompleted

timestamp

Remediation completion date (milliseconds)

Notes

string

Verification notes

Example

cURL

curl -X POST https://your-instance.com/api/verifications/all \
  -H "FACTION-API-KEY: your-api-key" \
  -d "start=2024-01-01" \
  -d "end=2024-12-31"

Get Assessor Verification Queue

Requires Assessor or Manager permission

Retrieve verifications assigned to the authenticated user. Does not include passed/failed verifications.

GET /api/verifications/queue

Request Parameters

FACTION-API-KEY

string

required

API authentication key

Response

Returns only verifications assigned to the authenticated user that are not yet completed. Response format matches /all endpoint.

Example

cURL

curl https://your-instance.com/api/verifications/queue \
  -H "FACTION-API-KEY: your-api-key"

Get User Verifications

Requires Remediation permission

Retrieve all verifications for a specific user, optionally filtered by date range.

POST /api/verifications/userQueue

Request Parameters

FACTION-API-KEY

string

required

API authentication key

username

string

required

Username of the assessor to query

start

date

Filter by completed date range start (format: YYYY-MM-DD)

end

date

Filter by completed date range end (format: YYYY-MM-DD)

Response

Returns all open verifications for the specified user and completed verifications within the date range. Response format matches /all endpoint.

Example

cURL

curl -X POST https://your-instance.com/api/verifications/userQueue \
  -H "FACTION-API-KEY: your-api-key" \
  -d "username=jsmith" \
  -d "start=2024-01-01" \
  -d "end=2024-12-31"

Pass or Fail a Verification

Requires Remediation, Assessor, or Manager permission

Mark a verification as passed or failed and optionally close the vulnerability.

POST /api/verifications/passfail

Request Parameters

FACTION-API-KEY

string

required

API authentication key

verificationID

long

required

Verification ID to complete

passed

boolean

required

true if the retest passed, false if it failed

notes

string

Notes about the verification result

inProd

boolean

If true and verification passed, closes the finding in production. Otherwise closes in development only.

completedDate

date

Date of completion (format: YYYY-MM-DD). If blank, current date is used.

Behavior

If passed is true, the vulnerability is marked as closed in development (or production if inProd=true)
A note is automatically added to the vulnerability with the assessor’s name, result, and provided notes
The verification is removed from the queue after completion

Example

cURL

curl -X POST https://your-instance.com/api/verifications/passfail \
  -H "FACTION-API-KEY: your-api-key" \
  -d "verificationID=123" \
  -d "passed=true" \
  -d "inProd=true" \
  -d "notes=Confirmed XSS is fixed in production"

Schedule a Retest

Requires Remediation or Manager permission

Create a new verification/retest for a vulnerability.

POST /api/verifications/retest

Request Parameters

FACTION-API-KEY

string

required

API authentication key

assessorId

string

required

Username of the assessor to assign

remediationId

string

Username of the remediation contact

vulnId

long

Vulnerability ID to retest (use either vulnId or trackingId)

trackingId

string

Vulnerability tracking ID to retest (use either vulnId or trackingId)

start

date

required

Verification start date (format: YYYY-MM-DD)

end

date

required

Verification end date (format: YYYY-MM-DD)

Response

Returns the newly created Verification ID.

{
  "result": "SUCCESS",
  "verificationId": 456
}

Example

cURL

curl -X POST https://your-instance.com/api/verifications/retest \
  -H "FACTION-API-KEY: your-api-key" \
  -d "assessorId=jsmith" \
  -d "remediationId=alee" \
  -d "trackingId=VID-1234" \
  -d "start=2024-02-01" \
  -d "end=2024-02-05"

Workflow States

Verifications progress through workflow states:

State	Value	Description
In Assessor Queue	0	Waiting for assessor to verify fix
Completed	N/A	Verification completed (passed or failed)

When a verification is marked as passed/failed via /passfail, it is removed from the queue and the result is recorded on the vulnerability.

Integration Example

Complete retest workflow using JavaScript:

// 1. Schedule a retest
const scheduleRetest = await fetch('/api/verifications/retest', {
  method: 'POST',
  headers: {
    'FACTION-API-KEY': apiKey,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    assessorId: 'jsmith',
    trackingId: 'VID-5678',
    start: '2024-02-01',
    end: '2024-02-05'
  })
});

const { verificationId } = await scheduleRetest.json();

// 2. Assessor retrieves their queue
const queue = await fetch('/api/verifications/queue', {
  headers: { 'FACTION-API-KEY': assessorApiKey }
});

const verifications = await queue.json();

// 3. Complete the verification
const result = await fetch('/api/verifications/passfail', {
  method: 'POST',
  headers: {
    'FACTION-API-KEY': assessorApiKey,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    verificationID: verificationId,
    passed: 'true',
    inProd: 'true',
    notes: 'Verified fix in production environment'
  })
});

Best Practices

Use tracking IDs instead of vulnerability IDs when scheduling retests from external systems

Date ranges: When querying verifications, use date ranges to limit results to specific time periods
Production closures: Only set inProd=true when you’ve verified the fix in production, not just development
Notes: Always include detailed notes when passing/failing verifications for audit trail
Workflow integration: Integrate with ticketing systems (Jira, ServiceNow) using the API to automatically schedule retests when remediation tickets are closed

Error Responses

Code	Message	Cause
401	Not Authorized	Invalid API key or insufficient permissions
400	Verification does not exist	Invalid verification ID
400	User does not exist	Invalid username in `/userQueue`

Overview

Endpoints

Verifications API

Authentication

Get All Verifications

Request Parameters

Response

Example

Get Assessor Verification Queue

Request Parameters

Response

Example

Get User Verifications

Request Parameters

Response

Example

Pass or Fail a Verification

Request Parameters

Behavior

Example

Schedule a Retest

Request Parameters

Response

Example

Workflow States

Integration Example

Best Practices

Error Responses

Build docs developers (and LLMs) love

Overview

Endpoints

​Authentication

​Get All Verifications

​Request Parameters

​Response

​Example

​Get Assessor Verification Queue

​Request Parameters

​Response

​Example

​Get User Verifications

​Request Parameters

​Response

​Example

​Pass or Fail a Verification

​Request Parameters

​Behavior

​Example

​Schedule a Retest

​Request Parameters

​Response

​Example

​Workflow States

​Integration Example

​Best Practices

​Error Responses

Build docs developers (and LLMs) love

Authentication

Get All Verifications

Request Parameters

Response

Example

Get Assessor Verification Queue

Request Parameters

Response

Example

Get User Verifications

Request Parameters

Response

Example

Pass or Fail a Verification

Request Parameters

Behavior

Example

Schedule a Retest

Request Parameters

Response

Example

Workflow States

Integration Example

Best Practices

Error Responses