Reports

Reports represent background check orders. Each report is tied to a candidate and a package, and contains individual check items with their own statuses and results.

Report Status Values

pending_candidate	Waiting for the candidate to complete their information
processing	Checks are actively running
complete	All checks have finished
dispute	Candidate has disputed one or more results
suspended	Report has been paused by an admin

POST/v1/reports

Order a Background Check

Creates a new report and starts the background check process for the given candidate and package combination.

Request Body

Field	Type	Required	Description
candidateId	string	Yes	ID of an existing candidate
packageId	string	Yes	ID of the package to run
workState	string	No	Two-letter US state code for state-specific checks
metadata	object	No	Arbitrary key-value pairs for your own use

Example Request

curl

curl -X POST https://api.coreverify.com/v1/reports \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateId": "cand_7xKm2pQrNvLw",
    "packageId": "pkg_standard_criminal",
    "workState": "CA"
  }'

Response

201 Created

{
  "data": {
    "id": "rpt_3FpQwLvMcYnR",
    "candidateId": "cand_7xKm2pQrNvLw",
    "packageId": "pkg_standard_criminal",
    "status": "pending_candidate",
    "assessment": null,
    "workState": "CA",
    "checks": [],
    "createdAt": "2024-03-15T14:30:00Z",
    "updatedAt": "2024-03-15T14:30:00Z"
  }
}

GET/v1/reports

List Reports

Returns a paginated list of all reports in your account, sorted by creation date descending.

Query Parameters

Parameter	Type	Description
status	string	Filter by report status
assessment	string	Filter by adjudication assessment: `clear`, `consider`, `adverse_action`
candidateId	string	Filter to reports for a specific candidate
from	string	ISO 8601 — reports created on or after this date
to	string	ISO 8601 — reports created on or before this date
page	integer	Page number (default: 1)
per_page	integer	Results per page, max 100 (default: 25)

Example Response

200 OK

{
  "data": [
    {
      "id": "rpt_3FpQwLvMcYnR",
      "candidateId": "cand_7xKm2pQrNvLw",
      "packageId": "pkg_standard_criminal",
      "status": "complete",
      "assessment": "clear",
      "workState": "CA",
      "createdAt": "2024-03-15T14:30:00Z",
      "completedAt": "2024-03-16T09:15:00Z"
    },
    {
      "id": "rpt_8TkBzXrJdWqM",
      "candidateId": "cand_9mWn4bRsTeXz",
      "packageId": "pkg_standard_criminal",
      "status": "processing",
      "assessment": null,
      "workState": "NY",
      "createdAt": "2024-03-14T10:00:00Z",
      "completedAt": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 87,
    "total_pages": 4
  }
}

GET/v1/reports/:id

Retrieve a Report

Returns the full details of a single report including all individual check items.

Check Item Fields

Field	Type	Description
id	string	Unique check item ID
type	string	Check type (e.g. `criminal_national`, `ssn_trace`, `employment_verification`)
status	string	`pending`, `processing`, `complete`, `suspended`
assessment	string \| null	`clear`, `consider`, or `null` while pending
result	object \| null	Raw result data specific to the check type
completedAt	string \| null	ISO 8601 timestamp when this check finished

Example Response

200 OK

{
  "data": {
    "id": "rpt_3FpQwLvMcYnR",
    "candidateId": "cand_7xKm2pQrNvLw",
    "packageId": "pkg_standard_criminal",
    "status": "complete",
    "assessment": "clear",
    "adjudicatedBy": null,
    "adjudicationNotes": null,
    "workState": "CA",
    "checks": [
      {
        "id": "chk_1AbCdEfGhIjK",
        "type": "ssn_trace",
        "status": "complete",
        "assessment": "clear",
        "result": {
          "identitiesFound": 1,
          "addressHistory": ["San Francisco, CA", "Austin, TX"]
        },
        "completedAt": "2024-03-16T08:02:00Z"
      },
      {
        "id": "chk_2LmNoPqRsTuV",
        "type": "criminal_national",
        "status": "complete",
        "assessment": "clear",
        "result": {
          "recordsFound": 0
        },
        "completedAt": "2024-03-16T09:10:00Z"
      },
      {
        "id": "chk_3WxYzAbCdEfG",
        "type": "sex_offender",
        "status": "complete",
        "assessment": "clear",
        "result": {
          "recordsFound": 0
        },
        "completedAt": "2024-03-16T09:12:00Z"
      }
    ],
    "metadata": {},
    "createdAt": "2024-03-15T14:30:00Z",
    "completedAt": "2024-03-16T09:15:00Z",
    "updatedAt": "2024-03-16T09:15:00Z"
  }
}

PATCH/v1/reports/:id/adjudicate

Adjudicate a Report

Record an adjudication decision on a completed report. Once adjudicated, the report assessment is set and cannot be changed.

Request Body

Field	Type	Required	Description
decision	string	Yes	`clear` or `adverse_action`
notes	string	No	Internal notes about the decision (not shared with candidate)

Example Request

curl

curl -X PATCH https://api.coreverify.com/v1/reports/rpt_3FpQwLvMcYnR/adjudicate \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "decision": "adverse_action",
    "notes": "Undisclosed felony conviction within past 7 years"
  }'