Findings API

The latest result of each legal check for a site, with citations, evidence references and remediation.

Operation	Endpoint
List findings	`GET /v1/findings`
Retrieve a finding	`GET /v1/findings/{finding}`
Triage a finding	`POST /v1/findings/{finding}`

The Finding object

The latest result of one legal check for a site.

Field	Type	Description
`id`	string	Unique identifier of the finding (fnd_…).
`object`	enum	String representing the object's type. Always "finding".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`site`	string	The site.
`check_id`	string	Stable id of the legal check.
`title`	string	Short title.
`detail`	string	What was observed.
`stage`	enum	Lifecycle stage. One of `signup`, `confirmation`, `reminder`, `cancellation`, `config`.
`severity`	enum	Strictest severity among the applicable requirements. One of `critical`, `high`, `medium`, `low`.
`status`	enum	Latest check result. One of `pass`, `fail`, `needs_review`, `not_applicable`.
`state`	enum	Triage state. One of `open`, `acknowledged`, `resolved`, `accepted_risk`.
`note`	string \| null	Triage note.
`jurisdictions`	array of enum	Jurisdictions whose laws this check applies.
`requirements`	array of RequirementRefs	The legal requirements behind the check, with citations.
`remediation`	Remediation \| null	How to fix the finding (see also the fixes resource and compliance plans).
`confidence`	number	Confidence 0-1 of the check result.
`evidence_refs`	array of strings	Ids of the captures / emails / evidence records supporting the result.
`details`	object	Check-specific details (failing regions/devices/URLs, measurements, quotes).
`evidence`	VerdictEvidence	What a verdict was based on. Never a pass without it; needs_review says what is missing.
`compliance_status`	enum	User-facing status. needs_fix (a requirement is clearly not met: `compliance.fix` is the one change), pending_live_check (everything Checkbox can see is right; the live event has not been observed yet — counts as compliant), verified_live (observed live: proof run, real BCC'd send, Stripe-confirmed cancellation), your_call (a real decision for a person: `compliance.question`), compliant (passes; grey areas carry a `compliance.note`), not_applicable, not_set_up (no sign the email or setting exists yet: `compliance.fix` is the one-click way to set it up; never counts as compliant), not_checked (Checkbox has not tried it yet, e.g. the cancel flow: `compliance.fix` says how; never counts as compliant). One of `needs_fix`, `pending_live_check`, `verified_live`, `your_call`, `compliant`, `not_applicable`, `not_set_up`, `not_checked`.
`compliance`	ComplianceInfo	What a person should do about one check (the user-facing layer over `status`).
`scan`	string \| null	Scan that produced the latest result.
`first_seen`	integer	First time the check was evaluated. Unix timestamp in seconds.
`last_seen`	integer	Latest evaluation. Unix timestamp in seconds.
`resolved_at`	integer \| null	When it was resolved. Unix timestamp in seconds.

List findings

GET /v1/findings

Findings ordered by urgency (failing first, then by severity). Filter by site, status (fail, needs_review, pass, not_applicable) and state (open, acknowledged, resolved, accepted_risk). Fix the open fail findings to become compliant.

Scope findings:read · Operation listFindings

SDK: checkbox.findings.list() (Node) · checkbox.findings.list() (Python). MCP / agents: operation listFindings.

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_…).
`status`	query	enum	Only this check status. One of `pass`, `fail`, `needs_review`, `not_applicable`.
`state`	query	enum	Only this triage state. One of `open`, `acknowledged`, `resolved`, `accepted_risk`.

Returns

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

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

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

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

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

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

import os
from checkbox import Checkbox

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

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "finding",
      "livemode": false,
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "check_id": "signup.disclosure_clear_conspicuous",
      "title": "Auto-renewal terms are not shown before purchase",
      "detail": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button.",
      "stage": "signup",
      "severity": "high",
      "status": "fail",
      "state": "open",
      "note": null,
      "jurisdictions": [
        "US-CA"
      ],
      "requirements": [
        {
          "id": "US-CA.17602.a.1",
          "jurisdiction": "US-CA",
          "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)",
          "title": "Clear and conspicuous auto-renewal terms before purchase",
          "source_url": "https://leginfo.legislature.ca.gov/…"
        }
      ],
      "remediation": {
        "summary": "Show the auto-renewal terms next to the subscribe button.",
        "steps": [
          "Add the disclosure above the button"
        ],
        "platform": "stripe",
        "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.",
        "snippet": {
          "language": "html",
          "code": "<p class=\"renewal-terms\">…</p>"
        }
      },
      "confidence": 0.9,
      "evidence_refs": [],
      "details": {
        "failingRegions": [
          "US-CA"
        ]
      },
      "evidence": {
        "summary": "The checkout says “every week”, but the plan is billed every 2 weeks.",
        "items": [
          {
            "source": "page",
            "ref": "cap_123",
            "url": "https://shop.example/checkout",
            "quote": "renews automatically every month at $19.99 until you cancel",
            "selector": "form > p.terms",
            "rect": {},
            "field": "cancellation.selfServeOnline",
            "value": true,
            "label": "US-CA desktop",
            "status": "fail",
            "detail": "no statement that the subscription renews automatically",
            "screenshot_ref": "ev_123",
            "at": "2026-11-01T10:00:00.000Z"
          }
        ],
        "missing": "A test cancellation, or a captured account page with the cancel option."
      },
      "compliance_status": "pending_live_check",
      "compliance": {
        "status": "pending_live_check",
        "label": "Looks compliant — live check pending",
        "reason": "template_only",
        "tier": "required",
        "fix": "Add \"until you cancel\" to the renewal line.",
        "note": null,
        "pending_live_check": {
          "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"
        },
        "question": {
          "text": "Your terms include a notice period. Keep it?",
          "recommended": "Remove it: let subscribers cancel online any time.",
          "why": "Commitments are legal in some states only when disclosed and agreed to."
        }
      },
      "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "first_seen": 1793318400,
      "last_seen": 1793318400,
      "resolved_at": 1793318400
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Retrieve a finding

GET /v1/findings/{finding}

One finding with its legal requirements (citations), evidence references and remediation.

Scope findings:read · Operation retrieveFinding

SDK: checkbox.findings.retrieve() (Node) · checkbox.findings.retrieve() (Python). MCP / agents: operation retrieveFinding.

Parameters

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

Returns

Returns a Finding object.

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

curl https://app.checkbox.site/v1/findings/fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

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

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

const finding = await checkbox.findings.retrieve('fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(finding);

import os
from checkbox import Checkbox

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

finding = checkbox.findings.retrieve("fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(finding)

Response

{
  "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "finding",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "check_id": "signup.disclosure_clear_conspicuous",
  "title": "Auto-renewal terms are not shown before purchase",
  "detail": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button.",
  "stage": "signup",
  "severity": "high",
  "status": "fail",
  "state": "open",
  "note": null,
  "jurisdictions": [
    "US-CA",
    "US-NY"
  ],
  "requirements": [
    {
      "id": "US-CA.17602.a.1",
      "jurisdiction": "US-CA",
      "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)",
      "title": "Clear and conspicuous auto-renewal terms before purchase",
      "source_url": "https://leginfo.legislature.ca.gov/…"
    }
  ],
  "remediation": {
    "summary": "Show the auto-renewal terms next to the subscribe button.",
    "steps": [
      "Add the disclosure above the button"
    ],
    "platform": "stripe",
    "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.",
    "snippet": {
      "language": "html",
      "code": "<p class=\"renewal-terms\">…</p>"
    }
  },
  "confidence": 0.9,
  "evidence_refs": [],
  "details": {
    "failingRegions": [
      "US-CA"
    ]
  },
  "evidence": {
    "summary": "The checkout says “every week”, but the plan is billed every 2 weeks.",
    "items": [
      {
        "source": "page",
        "ref": "cap_123",
        "url": "https://shop.example/checkout",
        "quote": "renews automatically every month at $19.99 until you cancel",
        "selector": "form > p.terms",
        "rect": {
          "x": 680,
          "y": 592,
          "width": 480,
          "height": 63
        },
        "field": "cancellation.selfServeOnline",
        "value": true,
        "label": "US-CA desktop",
        "status": "fail",
        "detail": "no statement that the subscription renews automatically",
        "screenshot_ref": "ev_123",
        "at": "2026-11-01T10:00:00.000Z"
      }
    ],
    "missing": "A test cancellation, or a captured account page with the cancel option."
  },
  "compliance_status": "pending_live_check",
  "compliance": {
    "status": "pending_live_check",
    "label": "Looks compliant — live check pending",
    "reason": "template_only",
    "tier": "required",
    "fix": "Add \"until you cancel\" to the renewal line.",
    "note": null,
    "pending_live_check": {
      "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"
    },
    "question": {
      "text": "Your terms include a notice period. Keep it?",
      "recommended": "Remove it: let subscribers cancel online any time.",
      "why": "Commitments are legal in some states only when disclosed and agreed to."
    }
  },
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "first_seen": 1793318400,
  "last_seen": 1793318400,
  "resolved_at": 1793318400
}

Triage a finding

POST /v1/findings/{finding}

Sets the triage state (open, acknowledged, accepted_risk, resolved) and an optional note. Triage does not change the check result; fixing the issue and re-scanning does.

Scope findings:write · Idempotent (send Idempotency-Key) · Operation updateFinding

SDK: checkbox.findings.update() (Node) · checkbox.findings.update() (Python). MCP / agents: operation updateFinding.

Parameters

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

Body

Field	Type	Description
`state` required	enum	New triage state. One of `open`, `acknowledged`, `resolved`, `accepted_risk`.
`note`	string	Why (kept with the finding).

Returns

Returns a Finding object.

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

curl https://app.checkbox.site/v1/findings/fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "acknowledged"
}'

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

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

const finding = await checkbox.findings.update('fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { state: 'acknowledged' });
console.log(finding);

import os
from checkbox import Checkbox

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

finding = checkbox.findings.update("fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", state="acknowledged")
print(finding)

Response

{
  "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "finding",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "check_id": "signup.disclosure_clear_conspicuous",
  "title": "Auto-renewal terms are not shown before purchase",
  "detail": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button.",
  "stage": "signup",
  "severity": "high",
  "status": "fail",
  "state": "open",
  "note": null,
  "jurisdictions": [
    "US-CA",
    "US-NY"
  ],
  "requirements": [
    {
      "id": "US-CA.17602.a.1",
      "jurisdiction": "US-CA",
      "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)",
      "title": "Clear and conspicuous auto-renewal terms before purchase",
      "source_url": "https://leginfo.legislature.ca.gov/…"
    }
  ],
  "remediation": {
    "summary": "Show the auto-renewal terms next to the subscribe button.",
    "steps": [
      "Add the disclosure above the button"
    ],
    "platform": "stripe",
    "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.",
    "snippet": {
      "language": "html",
      "code": "<p class=\"renewal-terms\">…</p>"
    }
  },
  "confidence": 0.9,
  "evidence_refs": [],
  "details": {
    "failingRegions": [
      "US-CA"
    ]
  },
  "evidence": {
    "summary": "The checkout says “every week”, but the plan is billed every 2 weeks.",
    "items": [
      {
        "source": "page",
        "ref": "cap_123",
        "url": "https://shop.example/checkout",
        "quote": "renews automatically every month at $19.99 until you cancel",
        "selector": "form > p.terms",
        "rect": {
          "x": 680,
          "y": 592,
          "width": 480,
          "height": 63
        },
        "field": "cancellation.selfServeOnline",
        "value": true,
        "label": "US-CA desktop",
        "status": "fail",
        "detail": "no statement that the subscription renews automatically",
        "screenshot_ref": "ev_123",
        "at": "2026-11-01T10:00:00.000Z"
      }
    ],
    "missing": "A test cancellation, or a captured account page with the cancel option."
  },
  "compliance_status": "pending_live_check",
  "compliance": {
    "status": "pending_live_check",
    "label": "Looks compliant — live check pending",
    "reason": "template_only",
    "tier": "required",
    "fix": "Add \"until you cancel\" to the renewal line.",
    "note": null,
    "pending_live_check": {
      "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"
    },
    "question": {
      "text": "Your terms include a notice period. Keep it?",
      "recommended": "Remove it: let subscribers cancel online any time.",
      "why": "Commitments are legal in some states only when disclosed and agreed to."
    }
  },
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "first_seen": 1793318400,
  "last_seen": 1793318400,
  "resolved_at": 1793318400
}

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.

Findings API

#The Finding object

#List findings

#Parameters

#Returns

#Retrieve a finding

#Parameters

#Returns

#Triage a finding

#Parameters

#Body

#Returns

The Finding object

List findings

Parameters

Returns

Retrieve a finding

Parameters

Returns

Triage a finding

Parameters

Body

Returns