Sites API

View as Markdown Open in Claude

The subscription businesses Checkbox monitors, how to install the snippet, and domain verification (which activates live mode).

Operation	Endpoint
List sites	`GET /v1/sites`
Create a site	`POST /v1/sites`
Retrieve a site	`GET /v1/sites/{site}`
Update a site	`POST /v1/sites/{site}`
Archive a site	`DELETE /v1/sites/{site}`
Restore an archived site	`POST /v1/sites/{site}/restore`
Retrieve domain verification	`GET /v1/sites/{site}/domain_verification`
Start domain verification	`POST /v1/sites/{site}/domain_verification`
Check domain verification now	`POST /v1/sites/{site}/domain_verification/check`

The Site object

A subscription business Checkbox monitors.

Field	Type	Description
`id`	string	Unique identifier of the site (site_…).
`object`	enum	String representing the object's type. Always "site".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`name`	string	Display name.
`url`	string	Base URL.
`platform`	enum	Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`.
`jurisdictions`	array of enum	Evaluated jurisdictions (empty = all).
`facts`	SiteFacts	Business facts that decide which legal requirements apply.
`checkout`	object	Synthetic-shopper configuration (secrets are never returned).
`checkout.url`	string	Checkout entry page.
`checkout.regions`	array of enum	States scanned from.
`checkout.devices`	array of enum	Devices scanned.
`checkout.checkout_steps`	integer	Number of configured checkout steps.
`checkout.completes_purchase`	boolean	A synthetic sign-up is configured.
`checkout.has_test_account`	boolean	A test account for the cancellation test is configured.
`checkout.test_account`	object \| null	The test account as configured (the password is write-only and never returned).
`checkout.cancel_steps`	integer	Number of explicit cancellation steps.
`monitoring`	SiteMonitoring	Scheduled monitoring.
`compliance`	SiteCompliance \| null	Latest verdict; null until the first evaluation.
`install`	SiteInstall	What to install on the merchant site.
`archived`	boolean	Archived (soft-deleted); evidence is retained.
`created`	integer	When the site was created. Unix timestamp in seconds.
`latest_scan`	Scan	Most recent scan (only with expand[]=latest_scan).
`domain_verification`	DomainVerification	Domain verification (only with expand[]=domain_verification).

List sites

GET /v1/sites

Returns the sites of the account in the current mode, newest first. Archived sites are included only with archived=true.

Scope sites:read · Operation listSites

SDK: checkbox.sites.list() (Node) · checkbox.sites.list() (Python). MCP / agents: operation listSites.

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).
`archived`	query	enum	true lists only archived sites. One of `true`, `false`.

Returns

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

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

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

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

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

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

import os
from checkbox import Checkbox

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

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "site",
      "livemode": false,
      "name": "Acme Coffee Club",
      "url": "https://acme.example",
      "platform": "stripe",
      "jurisdictions": [],
      "facts": {
        "has_free_trial": true,
        "trial_days": 14,
        "term_months": 1,
        "online_signup": true,
        "sells_goods": false,
        "notice_channel_email": true,
        "price_increase_consent_or_refund": false,
        "payment_methods": [
          "card"
        ]
      },
      "checkout": {
        "url": "https://acme.example/pricing",
        "regions": [
          "US-CA"
        ],
        "devices": [
          "desktop"
        ],
        "checkout_steps": 0,
        "completes_purchase": false,
        "has_test_account": false,
        "test_account": {
          "login_url": "https://acme.example/login",
          "email": "test-subscriber@acme.example"
        },
        "cancel_steps": 0
      },
      "monitoring": {
        "enabled": true,
        "interval_minutes": 1440,
        "held_for_activation": false,
        "last_scanned": 1793318400
      },
      "compliance": {
        "score": 82,
        "insurable": false,
        "evaluated": 1793318400,
        "open_findings": 2,
        "needs_review": 1
      },
      "install": {
        "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
        "snippet_key": "ab12cd34ef56",
        "inbound_email": "ab12cd34ef56@in.checkbox.site",
        "webhook_urls": {
          "stripe": "https://app.checkbox.site/webhooks/stripe/…"
        }
      },
      "archived": false,
      "created": 1793318400,
      "latest_scan": {
        "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "object": "scan",
        "livemode": false,
        "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "status": "completed",
        "trigger": "api",
        "regions": [
          "US-CA"
        ],
        "error": null,
        "warnings": [],
        "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "score": 82,
        "insurable": false,
        "started": 1793318400,
        "finished": 1793318400,
        "created": 1793318400
      },
      "domain_verification": {
        "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "object": "domain_verification",
        "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "domain": "acme.example",
        "status": "pending",
        "method": null,
        "verified_at": 1793318400,
        "last_checked": 1793318400,
        "last_error": "TXT record not found",
        "dns_record": {
          "type": "TXT",
          "name": "_checkbox-verify.acme.example",
          "value": "checkbox-verify=Xy…"
        },
        "file": {
          "url": "https://acme.example/.well-known/checkbox-verify.txt",
          "contents": "Xy…"
        },
        "scan_target_problems": [],
        "account_activated": false,
        "next_action": {
          "type": "publish_dns_record",
          "message": "Publish the TXT record, then call checkDomainVerification.",
          "operation_id": "checkDomainVerification",
          "mcp_tool": "call_api"
        }
      }
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Create a site

POST /v1/sites

Registers a subscription business. Only url is required; Checkbox derives the name and uses the URL as the checkout entry page. The response includes install (snippet tag, inbound email, platform webhook URLs). Next: install the snippet, then run createScan (or let checkbox init do both). In live mode before activation, monitoring is held until a domain is verified; in test mode, monitoring of a host that is not localhost or a domain the account verified is held the same way, and on-demand scans of such hosts are limited to a few a day.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation createSite

SDK: checkbox.sites.create() (Node) · checkbox.sites.create() (Python). MCP / agents: operation createSite.

Body

Field	Type	Description
`name`	string	Display name.
`url` required	string	Base URL of the business website.
`platform`	enum	Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`.
`jurisdictions`	array of enum	Jurisdictions to evaluate (empty = all US laws).
`facts`	SiteFacts	Business facts that decide which legal requirements apply.
`checkout_url`	string	Page with the subscribe button (defaults to url). Not a Stripe-hosted session link.
`checkout_steps`	array of ScanSteps	Steps to reach the final pre-payment screen.
`purchase`	SitePurchase	How the synthetic shopper completes a real (free) sign-up.
`test_account`	SiteTestAccount	A test customer account the synthetic shopper uses to try cancelling online.
`cancel_steps`	array of ScanSteps	Explicit cancellation steps (otherwise auto-discovered).
`regions`	array of enum	States the synthetic shopper visits from.
`devices`	array of enum	Devices to emulate.
`monitoring_interval_minutes`	integer	Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode.

Returns

Returns a Site object.

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

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

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

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

const site = await checkbox.sites.create({ url: 'https://acme.example' });
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.create(url="https://acme.example")
print(site)

Response

{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "scan",
    "livemode": false,
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "status": "completed",
    "trigger": "api",
    "regions": [
      "US-CA"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "score": 82,
    "insurable": false,
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}

Retrieve a site

GET /v1/sites/{site}

Returns a site with its latest compliance verdict (score, insurable) and install details.

Scope sites:read · Operation retrieveSite

SDK: checkbox.sites.retrieve() (Node) · checkbox.sites.retrieve() (Python). MCP / agents: operation retrieveSite.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).
`expand[]`	query	array of enum	Related objects to include inline: latest_scan, domain_verification. Pass as expand[]=name.

Returns

Returns a Site object.

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

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

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

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

const site = await checkbox.sites.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)

Response

{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "scan",
    "livemode": false,
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "status": "completed",
    "trigger": "api",
    "regions": [
      "US-CA"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "score": 82,
    "insurable": false,
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}

Update a site

POST /v1/sites/{site}

Updates the given fields; omitted fields keep their values. Changing url to another domain forgets the domain verification and ends the active certificate.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation updateSite

SDK: checkbox.sites.update() (Node) · checkbox.sites.update() (Python). MCP / agents: operation updateSite.

Parameters

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

Body

Field	Type	Description
`name`	string	Display name.
`url`	string	Base URL of the business website.
`platform`	enum	Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`.
`jurisdictions`	array of enum	Jurisdictions to evaluate (empty = all US laws).
`facts`	SiteFacts	Business facts that decide which legal requirements apply.
`checkout_url`	string	Page with the subscribe button (defaults to url). Not a Stripe-hosted session link.
`checkout_steps`	array of ScanSteps	Steps to reach the final pre-payment screen.
`purchase`	SitePurchase	How the synthetic shopper completes a real (free) sign-up.
`test_account`	SiteTestAccount	A test customer account the synthetic shopper uses to try cancelling online.
`cancel_steps`	array of ScanSteps	Explicit cancellation steps (otherwise auto-discovered).
`regions`	array of enum	States the synthetic shopper visits from.
`devices`	array of enum	Devices to emulate.
`monitoring_interval_minutes`	integer	Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode.

Returns

Returns a Site object.

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

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

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

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

const site = await checkbox.sites.update('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { name: 'Acme Coffee Club' });
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.update("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", name="Acme Coffee Club")
print(site)

Response

{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "scan",
    "livemode": false,
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "status": "completed",
    "trigger": "api",
    "regions": [
      "US-CA"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "score": 82,
    "insurable": false,
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}

Archive a site

DELETE /v1/sites/{site}

Archives (soft-deletes) the site: monitoring stops and it disappears from lists, but evidence and findings are retained for the warranty. Undo with restoreSite.

Scope sites:write · Operation deleteSite

SDK: checkbox.sites.del() (Node) · checkbox.sites.delete() (Python). MCP / agents: operation deleteSite.

Parameters

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

Returns

Returns a Site object.

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

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

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

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

const site = await checkbox.sites.del('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.delete("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)

Response

{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "scan",
    "livemode": false,
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "status": "completed",
    "trigger": "api",
    "regions": [
      "US-CA"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "score": 82,
    "insurable": false,
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}

Restore an archived site

POST /v1/sites/{site}/restore

Un-archives a site (counts against the fair-use site limit again).

Scope sites:write · Idempotent (send Idempotency-Key) · Operation restoreSite

SDK: checkbox.sites.restore() (Node) · checkbox.sites.restore() (Python). MCP / agents: operation restoreSite.

Parameters

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

Returns

Returns a Site object.

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

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

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

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

const site = await checkbox.sites.restore('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.restore("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)

Response

{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "scan",
    "livemode": false,
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "status": "completed",
    "trigger": "api",
    "regions": [
      "US-CA"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "score": 82,
    "insurable": false,
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}

Retrieve domain verification

GET /v1/sites/{site}/domain_verification

Status of the site domain verification, with the DNS record / file to publish.

Scope sites:read · Operation retrieveDomainVerification

SDK: checkbox.domainVerifications.retrieve() (Node) · checkbox.domain_verifications.retrieve() (Python). MCP / agents: operation retrieveDomainVerification.

Parameters

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

Returns

Returns a DomainVerification object.

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

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

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

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

const domainVerification = await checkbox.domainVerifications.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);

import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)

Response

{
  "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "domain_verification",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "domain": "acme.example",
  "status": "pending",
  "method": null,
  "verified_at": 1793318400,
  "last_checked": 1793318400,
  "last_error": "TXT record not found",
  "dns_record": {
    "type": "TXT",
    "name": "_checkbox-verify.acme.example",
    "value": "checkbox-verify=Xy…"
  },
  "file": {
    "url": "https://acme.example/.well-known/checkbox-verify.txt",
    "contents": "Xy…"
  },
  "scan_target_problems": [],
  "account_activated": false,
  "next_action": {
    "type": "publish_dns_record",
    "message": "Publish the TXT record, then call checkDomainVerification.",
    "operation_id": "checkDomainVerification",
    "mcp_tool": "call_api"
  }
}

Start domain verification

POST /v1/sites/{site}/domain_verification

Starts verification of the site domain and returns a DNS TXT record and a /.well-known file; publishing either proves control. Then call checkDomainVerification. Verifying a live-mode site activates live mode for the account (instant, self-serve).

Scope sites:write · Idempotent (send Idempotency-Key) · Operation createDomainVerification

SDK: checkbox.domainVerifications.create() (Node) · checkbox.domain_verifications.create() (Python). MCP / agents: operation createDomainVerification.

Parameters

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

Body

Field	Type	Description
`rotate`	boolean	Issue a new token (invalidates the old one).

Returns

Returns a DomainVerification object.

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

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

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

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

const domainVerification = await checkbox.domainVerifications.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);

import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)

Response

{
  "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "domain_verification",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "domain": "acme.example",
  "status": "pending",
  "method": null,
  "verified_at": 1793318400,
  "last_checked": 1793318400,
  "last_error": "TXT record not found",
  "dns_record": {
    "type": "TXT",
    "name": "_checkbox-verify.acme.example",
    "value": "checkbox-verify=Xy…"
  },
  "file": {
    "url": "https://acme.example/.well-known/checkbox-verify.txt",
    "contents": "Xy…"
  },
  "scan_target_problems": [],
  "account_activated": false,
  "next_action": {
    "type": "publish_dns_record",
    "message": "Publish the TXT record, then call checkDomainVerification.",
    "operation_id": "checkDomainVerification",
    "mcp_tool": "call_api"
  }
}

Check domain verification now

POST /v1/sites/{site}/domain_verification/check

Looks for the DNS TXT record and the /.well-known file now. On success in live mode, the account is activated and held monitoring starts.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation checkDomainVerification

SDK: checkbox.domainVerifications.check() (Node) · checkbox.domain_verifications.check() (Python). MCP / agents: operation checkDomainVerification.

Parameters

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

Returns

Returns a DomainVerification object.

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

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/domain_verification/check \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X POST

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

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

const domainVerification = await checkbox.domainVerifications.check('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);

import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.check("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)

Response

{
  "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "domain_verification",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "domain": "acme.example",
  "status": "pending",
  "method": null,
  "verified_at": 1793318400,
  "last_checked": 1793318400,
  "last_error": "TXT record not found",
  "dns_record": {
    "type": "TXT",
    "name": "_checkbox-verify.acme.example",
    "value": "checkbox-verify=Xy…"
  },
  "file": {
    "url": "https://acme.example/.well-known/checkbox-verify.txt",
    "contents": "Xy…"
  },
  "scan_target_problems": [],
  "account_activated": false,
  "next_action": {
    "type": "publish_dns_record",
    "message": "Publish the TXT record, then call checkDomainVerification.",
    "operation_id": "checkDomainVerification",
    "mcp_tool": "call_api"
  }
}

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.

Sites API

#The Site object

#List sites

#Parameters

#Returns

#Create a site

#Body

#Returns

#Retrieve a site

#Parameters

#Returns

#Update a site

#Parameters

#Body

#Returns

#Archive a site

#Parameters

#Returns

#Restore an archived site

#Parameters

#Returns

#Retrieve domain verification

#Parameters

#Returns

#Start domain verification

#Parameters

#Body

#Returns

#Check domain verification now

#Parameters

#Returns

The Site object

List sites

Parameters

Returns

Create a site

Body

Returns

Retrieve a site

Parameters

Returns

Update a site

Parameters

Body

Returns

Archive a site

Parameters

Returns

Restore an archived site

Parameters

Returns

Retrieve domain verification

Parameters

Returns

Start domain verification

Parameters

Body

Returns

Check domain verification now

Parameters

Returns