{ "openapi": "3.1.0", "info": { "title": "Companies House IDV Roster API", "version": "1.0.0", "description": "Companies House identity verification deadlines for agents. Paid calls are settled in USDC on Base (eip155:8453) to 0x491Fcf30a5aa0483B3cd8C0041d21801F195B3AF; no account or API key.", "contact": { "name": "Companies House IDV Roster", "url": "https://idv.adamhaleworks.workers.dev/about/" }, "x-guidance": "UK Companies House identity verification (IDV) deadlines for directors, LLP members and PSCs, computed from a CSV or JSON rows. POST /api/schedule is free for up to 5 companies. Paid endpoints use x402 v2 (scheme exact, USDC): an unpaid call returns HTTP 402 with the terms in the PAYMENT-REQUIRED header; retry with a PAYMENT-SIGNATURE header (e.g. @x402/fetch). Invalid input is rejected with 400 before payment. Request bodies are processed in memory and not stored. Workflow aid, not legal advice." }, "externalDocs": { "description": "Docs, prices and limits", "url": "https://idv.adamhaleworks.workers.dev/bulk/" }, "servers": [ { "url": "https://idv.adamhaleworks.workers.dev" } ], "x-x402": { "x402Version": 2, "scheme": "exact", "network": "eip155:8453", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x491Fcf30a5aa0483B3cd8C0041d21801F195B3AF", "facilitators": [ "https://facilitator.payai.network", "https://facilitator.xpay.sh" ] }, "paths": { "/api/schedule": { "post": { "operationId": "scheduleFree", "summary": "Identity verification schedule (free, up to 5 companies)", "description": "Use when you need each UK company director's, LLP member's and PSC's Companies House identity verification deadline or 14-day window. Send a CSV or JSON rows (company_number, person_name, role, appointed, cs_date, verified, psc_type, birth_month); get a sorted schedule with status (overdue, due soon, OK, verified, needs data), an .ics calendar and an Ed25519-signed evidence pack citing GOV.UK and SI 2025/1118. Free: the first 5 companies in the input; evidence pack not signed. Stateless: nothing is stored.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "description": "CSV text with a header row. Use either csv or rows." }, "rows": { "type": "array", "description": "Objects with the CSV column names as keys.", "items": { "type": "object" } }, "asOf": { "type": "string", "description": "Status date YYYY-MM-DD (default: today in London)." }, "soonDays": { "type": "number", "description": "Days ahead that count as due soon (default 30)." } } }, "example": { "rows": [ { "company_number": "01234567", "company_name": "Example Bakery Ltd", "person_name": "SMITH, Jane", "role": "director", "appointed": "2014-05-02", "cs_date": "2026-11-05", "verified": "no" } ], "asOf": "2026-10-12" } }, "text/csv": { "schema": { "type": "string" } } } }, "responses": { "200": { "description": "Schedule", "content": { "application/json": { "schema": { "type": "object" }, "example": { "summary": { "rows": 1, "companies": 1, "counts": { "overdue": 0, "check": 0, "needs_data": 0, "due_soon": 0, "ok": 1, "verified": 0, "not_required": 0 }, "nextDeadline": "2026-11-19" }, "schedule": [ { "row": 2, "companyNumber": "01234567", "personName": "SMITH, Jane", "role": "director", "rule": "DIR_EXISTING", "windowStart": null, "deadline": "2026-11-19", "daysLeft": 38, "status": "ok" } ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limited" } } } }, "/x402/v1/schedule": { "post": { "operationId": "schedulePaid", "summary": "UK Companies House identity verification schedule", "description": "Use when you need each UK company director's, LLP member's and PSC's Companies House identity verification deadline or 14-day window. Send a CSV or JSON rows (company_number, person_name, role, appointed, cs_date, verified, psc_type, birth_month); get a sorted schedule with status (overdue, due soon, OK, verified, needs data), an .ics calendar and an Ed25519-signed evidence pack citing GOV.UK and SI 2025/1118. Up to 2000 rows per call. Stateless: nothing is stored. Price: $0.02 USDC per call on Base.", "tags": [ "x402" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Result (charged).", "content": { "application/json": { "schema": { "type": "object" }, "example": { "summary": { "rows": 1, "companies": 1, "counts": { "overdue": 0, "check": 0, "needs_data": 0, "due_soon": 0, "ok": 1, "verified": 0, "not_required": 0 }, "nextDeadline": "2026-11-19" }, "schedule": [ { "row": 2, "companyNumber": "01234567", "personName": "SMITH, Jane", "role": "director", "rule": "DIR_EXISTING", "windowStart": null, "deadline": "2026-11-19", "daysLeft": 38, "status": "ok" } ] } } } }, "400": { "description": "Invalid input, rejected before payment (not charged).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "Payment required. The x402 v2 PaymentRequired object is base64 JSON in the PAYMENT-REQUIRED header and repeated in the body.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "description": "CSV text with a header row. Use either csv or rows." }, "rows": { "type": "array", "description": "Objects with the CSV column names as keys.", "items": { "type": "object" } }, "asOf": { "type": "string", "description": "Status date YYYY-MM-DD (default: today in London)." }, "soonDays": { "type": "number", "description": "Days ahead that count as due soon (default 30)." } } }, "example": { "rows": [ { "company_number": "01234567", "company_name": "Example Bakery Ltd", "person_name": "SMITH, Jane", "role": "director", "appointed": "2014-05-02", "cs_date": "2026-11-05", "verified": "no" } ], "asOf": "2026-10-12" } }, "text/csv": { "schema": { "type": "string" } } } } } }, "/x402/v1/bulk-pass": { "get": { "operationId": "bulkPass", "summary": "IDV Roster bulk pass (30 days)", "description": "Buys a 30-day bulk pass (IDV1.… code) that unlocks unlimited rows and ZIP export in the browser-only IDV Roster planner (free tier: 5 companies). Paste the pass into the planner. No input needed. Price: $9 USDC per call on Base.", "tags": [ "x402" ], "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "9" }, "protocols": [ { "x402": {} } ] }, "responses": { "200": { "description": "Result (charged).", "content": { "application/json": { "schema": { "type": "object" }, "example": { "pass": "IDV1.eyJ2IjoxLC4uLn0.c2lnbmF0dXJl", "plan": "bulk", "expires": "2026-11-11", "use": "Paste the pass into the bulk pass box at https://idv.adamhaleworks.workers.dev/" } } } }, "400": { "description": "Invalid input, rejected before payment (not charged).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "Payment required. The x402 v2 PaymentRequired object is base64 JSON in the PAYMENT-REQUIRED header and repeated in the body.", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }