Evaluations API

Compliance verdicts: the compliance status (label and counts), with the blocking checks.

Operation	Endpoint
Re-evaluate a site now	`POST /v1/sites/{site}/evaluations`
List evaluations	`GET /v1/evaluations`
Retrieve an evaluation	`GET /v1/evaluations/{evaluation}`
Get the current verdict of a site	`GET /v1/sites/{site}/evaluation`

The Evaluation object

A compliance verdict for a site at a point in time.

Field	Type	Description
`id`	string	Unique identifier of the evaluation (eval_…).
`object`	enum	String representing the object's type. Always "evaluation".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`site`	string	The evaluated site.
`scan`	string	The scan row this evaluation belongs to.
`rules_version`	string	Legal catalog / rules version used.
`evaluated`	integer	When it was evaluated. Unix timestamp in seconds.
`observed`	integer \| null	Newest synthetic-shopper observation it used. Unix timestamp in seconds.
`summary`	object	Counts per status.
`summary.pass`	integer	Passing checks.
`summary.fail`	integer	Failing checks.
`summary.needs_review`	integer	Checks needing a human look.
`summary.not_applicable`	integer	Checks that do not apply.
`blockers`	array of CheckSummarys	Blocking checks: critical or high-severity checks that fail, are undecided (critical) or lack evidence (high).
`compliance`	ComplianceRollup	Roll-up of the user-facing statuses of the required checks.
`checks`	array of CheckSummarys	Every check evaluated.

Re-evaluate a site now

POST /v1/sites/{site}/evaluations

Re-runs the legal rules against the evidence already collected (no new scan) and returns the verdict synchronously. Use after changing site facts, or to get a verdict right after evidence arrived.

Scope evaluations:write · Idempotent (send Idempotency-Key) · Operation createEvaluation

SDK: checkbox.evaluations.create() (Node) · checkbox.evaluations.create() (Python). MCP / agents: operation createEvaluation.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).

Returns

Returns an Evaluation object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/evaluations \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const evaluation = await checkbox.evaluations.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(evaluation);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

evaluation = checkbox.evaluations.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(evaluation)

Response

{
  "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "evaluation",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "rules_version": "2026.10.1",
  "evaluated": 1793318400,
  "observed": 1793318400,
  "summary": {
    "pass": 20,
    "fail": 2,
    "needs_review": 1,
    "not_applicable": 9
  },
  "blockers": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ],
  "compliance": {
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "counts": {
      "needs_fix": 0,
      "your_call": 0,
      "pending_live_check": 2,
      "verified_live": 3,
      "compliant": 9,
      "not_applicable": 6,
      "not_set_up": 0,
      "not_checked": 0
    },
    "pending_live_checks": [
      {
        "what": "Your acknowledgment email, seen sent for a real sign-up",
        "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
        "action": "bcc_real_sends",
        "due": "2026-11-20"
      }
    ],
    "suggestions": 1,
    "checkouts": [
      {
        "name": "Annual",
        "kind": "payment_link",
        "plan": "Annual",
        "status": "pending_live_check",
        "label": "Needs a fix",
        "open": [
          {
            "check_id": "signup.disclosure.price",
            "title": "recurring charge is stated",
            "status": "pending_live_check"
          }
        ]
      }
    ]
  },
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ]
}

List evaluations

GET /v1/evaluations

Verdicts newest first (status history), optionally for one site.

Scope evaluations:read · Operation listEvaluations

SDK: checkbox.evaluations.list() (Node) · checkbox.evaluations.list() (Python). MCP / agents: operation listEvaluations.

Parameters

Parameter	In	Type	Description
`limit`	query	integer	Number of objects to return, 1-100 (default 10).
`starting_after`	query	string	Cursor: an object id; returns the objects after it (older).
`ending_before`	query	string	Cursor: an object id; returns the objects before it (newer).
`site`	query	string	Only objects of this site (site_…).

Returns

Returns a list ({ object: "list", data, has_more, url }) of Evaluation objects.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl -G https://app.checkbox.site/v1/evaluations \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const evaluations = await checkbox.evaluations.list({ limit: 3 });
console.log(evaluations.data);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

evaluations = checkbox.evaluations.list(limit=3)
print(evaluations.data)

Response

{
  "object": "list",
  "data": [
    {
      "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "evaluation",
      "livemode": false,
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "rules_version": "2026.10.1",
      "evaluated": 1793318400,
      "observed": 1793318400,
      "summary": {
        "pass": 20,
        "fail": 2,
        "needs_review": 1,
        "not_applicable": 9
      },
      "blockers": [
        {
          "check_id": "cancellation.online_cancel_available",
          "title": "Customers can cancel online",
          "status": "pass",
          "severity": "critical",
          "stage": "cancellation",
          "compliance_status": "pending_live_check"
        }
      ],
      "compliance": {
        "status": "compliant",
        "label": "Compliant · 2 live checks pending",
        "counts": {
          "needs_fix": 0,
          "your_call": 0,
          "pending_live_check": 2,
          "verified_live": 3,
          "compliant": 9,
          "not_applicable": 6,
          "not_set_up": 0,
          "not_checked": 0
        },
        "pending_live_checks": [
          {
            "what": "Your acknowledgment email, seen sent for a real sign-up",
            "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
            "action": "bcc_real_sends",
            "due": "2026-11-20"
          }
        ],
        "suggestions": 1,
        "checkouts": [
          {
            "name": "Annual",
            "kind": "payment_link",
            "plan": "Annual",
            "status": "pending_live_check",
            "label": "Needs a fix",
            "open": []
          }
        ]
      },
      "checks": [
        {
          "check_id": "cancellation.online_cancel_available",
          "title": "Customers can cancel online",
          "status": "pass",
          "severity": "critical",
          "stage": "cancellation",
          "compliance_status": "pending_live_check"
        }
      ]
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Retrieve an evaluation

GET /v1/evaluations/{evaluation}

Returns one verdict with all checks and the blocking checks.

Scope evaluations:read · Operation retrieveEvaluation

SDK: checkbox.evaluations.retrieve() (Node) · checkbox.evaluations.retrieve() (Python). MCP / agents: operation retrieveEvaluation.

Parameters

Parameter	In	Type	Description
`evaluation` required	path	string	Unique identifier of the evaluation (eval_…).

Returns

Returns an Evaluation object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/evaluations/eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const evaluation = await checkbox.evaluations.retrieve('eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(evaluation);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

evaluation = checkbox.evaluations.retrieve("eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(evaluation)

Response

{
  "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "evaluation",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "rules_version": "2026.10.1",
  "evaluated": 1793318400,
  "observed": 1793318400,
  "summary": {
    "pass": 20,
    "fail": 2,
    "needs_review": 1,
    "not_applicable": 9
  },
  "blockers": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ],
  "compliance": {
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "counts": {
      "needs_fix": 0,
      "your_call": 0,
      "pending_live_check": 2,
      "verified_live": 3,
      "compliant": 9,
      "not_applicable": 6,
      "not_set_up": 0,
      "not_checked": 0
    },
    "pending_live_checks": [
      {
        "what": "Your acknowledgment email, seen sent for a real sign-up",
        "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
        "action": "bcc_real_sends",
        "due": "2026-11-20"
      }
    ],
    "suggestions": 1,
    "checkouts": [
      {
        "name": "Annual",
        "kind": "payment_link",
        "plan": "Annual",
        "status": "pending_live_check",
        "label": "Needs a fix",
        "open": [
          {
            "check_id": "signup.disclosure.price",
            "title": "recurring charge is stated",
            "status": "pending_live_check"
          }
        ]
      }
    ]
  },
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ]
}

Get the current verdict of a site

GET /v1/sites/{site}/evaluation

The latest evaluation of the site: its compliance status and what blocks it. 404 resource_missing with next_action createScan when the site was never evaluated.

Scope evaluations:read · Operation retrieveLatestEvaluation

SDK: checkbox.evaluations.retrieveLatest() (Node) · checkbox.evaluations.retrieve_latest() (Python). MCP / agents: operation retrieveLatestEvaluation.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).

Returns

Returns an Evaluation object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/evaluation \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const evaluation = await checkbox.evaluations.retrieveLatest('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(evaluation);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

evaluation = checkbox.evaluations.retrieve_latest("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(evaluation)

Response

{
  "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "evaluation",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "rules_version": "2026.10.1",
  "evaluated": 1793318400,
  "observed": 1793318400,
  "summary": {
    "pass": 20,
    "fail": 2,
    "needs_review": 1,
    "not_applicable": 9
  },
  "blockers": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ],
  "compliance": {
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "counts": {
      "needs_fix": 0,
      "your_call": 0,
      "pending_live_check": 2,
      "verified_live": 3,
      "compliant": 9,
      "not_applicable": 6,
      "not_set_up": 0,
      "not_checked": 0
    },
    "pending_live_checks": [
      {
        "what": "Your acknowledgment email, seen sent for a real sign-up",
        "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
        "action": "bcc_real_sends",
        "due": "2026-11-20"
      }
    ],
    "suggestions": 1,
    "checkouts": [
      {
        "name": "Annual",
        "kind": "payment_link",
        "plan": "Annual",
        "status": "pending_live_check",
        "label": "Needs a fix",
        "open": [
          {
            "check_id": "signup.disclosure.price",
            "title": "recurring charge is stated",
            "status": "pending_live_check"
          }
        ]
      }
    ]
  },
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ]
}

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.

Evaluations API

#The Evaluation object

#Re-evaluate a site now

#Parameters

#Returns

#List evaluations

#Parameters

#Returns

#Retrieve an evaluation

#Parameters

#Returns

#Get the current verdict of a site

#Parameters

#Returns

The Evaluation object

Re-evaluate a site now

Parameters

Returns

List evaluations

Parameters

Returns

Retrieve an evaluation

Parameters

Returns

Get the current verdict of a site

Parameters

Returns