{ "openapi": "3.1.0", "info": { "title": "Zorro API", "version": "1.0.0", "summary": "UK company data: resolve one company, or enrich a list as a job.", "description": "The /v1 REST API. Every value comes back in an envelope that says where it came from, how current it is and whether to review it.", "contact": { "name": "Zorro support", "email": "support@getzorro.ai", "url": "https://getzorro.ai/docs/api" } }, "servers": [ { "url": "https://api.getzorro.ai", "description": "Production" } ], "security": [ { "ApiKey": [] } ], "tags": [ { "name": "Spec", "description": "This description, served from the API host. No key needed." }, { "name": "Key", "description": "Check a key and read the catalogue." }, { "name": "Resolve", "description": "Resolve one company in one request." }, { "name": "Jobs", "description": "Run a list of companies in the background." }, { "name": "Usage", "description": "See what your account has used." } ], "externalDocs": { "description": "Documentation", "url": "https://getzorro.ai/docs/api" }, "paths": { "/v1/openapi.json": { "get": { "operationId": "getOpenapi", "tags": [ "Spec" ], "summary": "Fetch this description", "description": "This description, from the host it describes. The response is a 302 to where the file is published, which is the same document you are reading now; follow redirects, as every HTTP client and code generator does by default.\n\nNo key is needed, and the answer is the same for every account. `/v1/openapi` answers identically.", "security": [], "responses": { "302": { "description": "Redirect to the published description.", "headers": { "Location": { "description": "Where the file is served.", "schema": { "type": "string" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/whoami": { "get": { "operationId": "getWhoami", "tags": [ "Key" ], "summary": "Check a key and see its access", "description": "This call confirms the key works and returns what it can do: its scopes, every block with its availability and tier, the row cap and the per-minute request allowance. The call is not billed and does not change data.\n\nRequired scope: `read`.", "x-required-scope": "read", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The key is valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoAmI" }, "examples": { "whoami_200": { "$ref": "#/components/examples/whoami_200" } } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "whoami_401_invalid": { "$ref": "#/components/examples/whoami_401_invalid" }, "whoami_401_missing": { "$ref": "#/components/examples/whoami_401_missing" } } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/blocks": { "get": { "operationId": "listBlocks", "tags": [ "Key" ], "summary": "List the block catalogue", "description": "This call returns every block with its description, source, availability for this key, tier, latency class and coverage, plus the confidence contract and the option vocabularies. The call is not billed and does not change data.\n\nRequired scope: `read`.", "x-required-scope": "read", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "The catalogue is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockCatalog" } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/resolve": { "get": { "operationId": "resolveCompany", "tags": [ "Resolve" ], "summary": "Resolve one company", "description": "Send one company and get its blocks back. The response carries a job_id, so the row can also be read from the job endpoints. The limit is 60 requests a minute per key.\n\nWith defer_live=true the response comes at once; blocks still being checked are {\"status\":\"pending\"} and are collected from results_url.\n\nRequired scope: `enrich`.", "x-required-scope": "enrich", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "company_number", "in": "query", "required": false, "description": "This is the Companies House number. Give exactly one of company_number, company_name or domain.", "schema": { "type": "string", "maxLength": 20 } }, { "name": "company_name", "in": "query", "required": false, "description": "This is the registered name. More than one live match answers 409 with candidates.", "schema": { "type": "string", "maxLength": 500 } }, { "name": "domain", "in": "query", "required": false, "description": "Provide a bare host or URL. A register, directory, social or site-builder host answers 404 not_own_site.", "schema": { "type": "string", "maxLength": 255 } }, { "name": "blocks", "in": "query", "required": false, "description": "Provide comma-separated block keys. By default, every block enabled for the key is returned. Blocks the key cannot have come back not_enabled with a warning; if none is left, the request answers 403.", "schema": { "type": "string" }, "style": "form", "explode": false }, { "name": "validation", "in": "query", "required": false, "description": "The domain_validation modes are none, rules, live, officers, ai. The default modes are rules,live.", "schema": { "type": "string" }, "style": "form", "explode": false }, { "name": "min_confidence", "in": "query", "required": false, "description": "Set your threshold from 0 to 1. The default is 0.5.", "schema": { "type": "number", "minimum": 0, "maximum": 1 } }, { "name": "defer_live", "in": "query", "required": false, "description": "When true, the response contains the available blocks; live blocks are pending and collected from results_url. This cannot be combined with wait=false or store=false.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "wait", "in": "query", "required": false, "description": "When false, the response is 202 with the job and results_url; collect the row from there.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "store", "in": "query", "required": false, "description": "When false, the row is not kept for later reads (expires_at null, stored false).", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "discover", "in": "query", "required": false, "description": "Specify the blocks to look up when the company has no value on file. This is off by default on resolve.", "schema": { "type": "string" }, "style": "form", "explode": false }, { "name": "max_live_lookups", "in": "query", "required": false, "description": "This sets the number of website searches allowed and defaults to 1 when discover is given.", "schema": { "type": "integer", "minimum": 0 } }, { "name": "ref", "in": "query", "required": false, "description": "This is your reference, which is echoed back.", "schema": { "type": "string", "maxLength": 120 } }, { "name": "read_accounts_pdf", "in": "query", "required": false, "description": "For financials_live, this reads PDF-only accounts. It is off by default.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "web_search", "in": "query", "required": false, "description": "This is a Premium option enabled per account.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "google_business", "in": "query", "required": false, "description": "For trading_address, this adds the listing check.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "contact_roles", "in": "query", "required": false, "description": "For contacts, the values are owner, director, finance, operations, in order of preference.", "schema": { "type": "string" }, "style": "form", "explode": false }, { "name": "max_contacts", "in": "query", "required": false, "description": "For contacts, use 1 to 5; the default is 3.", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "verify_emails", "in": "query", "required": false, "description": "For contacts, the default is true.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "contacts_lookup", "in": "query", "required": false, "description": "For contacts, use cached_only or live; the default is live.", "schema": { "type": "string", "enum": [ "cached_only", "live" ] } }, { "name": "include_phone", "in": "query", "required": false, "description": "For contacts, this returns a phone number per person. With contacts_lookup=live, it needs defer_live=true or wait=false; otherwise, the response is 400.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "include_linkedin", "in": "query", "required": false, "description": "For contacts, the default is true.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The company is returned. With defer_live, the response may be incomplete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveResponse" }, "examples": { "resolve_progressive_first_200": { "$ref": "#/components/examples/resolve_progressive_first_200" }, "resolve_warning_200": { "$ref": "#/components/examples/resolve_warning_200" } } } } }, "202": { "description": "With wait=false, the job is returned for you to poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "The input is invalid because it contains two identifiers, a conflicting flag pair, an unknown block or an invalid option (FieldErrors), or no usable identifier.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/FieldErrors" } ] }, "examples": { "resolve_400_defer_live_store": { "$ref": "#/components/examples/resolve_400_defer_live_store" }, "resolve_400_min_confidence": { "$ref": "#/components/examples/resolve_400_min_confidence" }, "resolve_400_two_keys": { "$ref": "#/components/examples/resolve_400_two_keys" }, "resolve_400_unknown_block": { "$ref": "#/components/examples/resolve_400_unknown_block" }, "resolve_400_validation_mode": { "$ref": "#/components/examples/resolve_400_validation_mode" } } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the enrich scope, or none of the requested blocks is enabled for it.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/NotEnabledError" }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "resolve_403_not_enabled": { "$ref": "#/components/examples/resolve_403_not_enabled" } } } } }, "404": { "description": "No company matched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveNotFound" }, "examples": { "resolve_404_not_matched": { "$ref": "#/components/examples/resolve_404_not_matched" }, "resolve_404_not_own_site": { "$ref": "#/components/examples/resolve_404_not_own_site" }, "resolve_404_site_unreachable": { "$ref": "#/components/examples/resolve_404_site_unreachable" } } } } }, "409": { "description": "More than one live company matched, with candidates; or the X-Idempotency-Key was used for a different request.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AmbiguousMatch" }, { "$ref": "#/components/schemas/Error" } ] }, "examples": { "resolve_409_ambiguous": { "$ref": "#/components/examples/resolve_409_ambiguous" } } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "resolve_429": { "$ref": "#/components/examples/resolve_429" } } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "We could not resolve the row (detail gives a reason such as resolver_error or source_unavailable). Retry the request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enrich/jobs": { "post": { "operationId": "createJob", "tags": [ "Jobs" ], "summary": "Submit a list as a job", "description": "Send up to 250,000 rows (or the key's own max_rows_per_job) and the requested blocks. The response is returned before the asynchronous job is complete. Poll the job, then page through its results.\n\nRequired scope: `enrich`.", "x-required-scope": "enrich", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreateRequest" }, "examples": { "websites": { "summary": "Three companies, website and website check", "value": { "rows": [ { "ref": "crm-1001", "company_number": "02805730" }, { "ref": "crm-1002", "company_number": "08130873" }, { "ref": "crm-1003", "company_number": "07706156" } ], "blocks": [ "domain", "domain_validation" ], "options": { "validation": [ "rules", "live" ] } } } } } } }, "responses": { "200": { "description": "A replay with the same X-Idempotency-Key and the same body. You get the original job and nothing new runs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "jobs_create_replay_200": { "$ref": "#/components/examples/jobs_create_replay_200" } } } } }, "202": { "description": "The job was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "jobs_create_202": { "$ref": "#/components/examples/jobs_create_202" } } } } }, "400": { "description": "The request body is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the enrich scope, no requested block is enabled, or a premium option is not enabled.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/NotEnabledError" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "409": { "description": "The X-Idempotency-Key was used for a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "jobs_create_409_idempotency": { "$ref": "#/components/examples/jobs_create_409_idempotency" } } } } }, "413": { "description": "The request contains more rows than the job or key allows. Split the file.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldErrors" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enrich/jobs/{job_id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "Get a job's status", "description": "This call returns the job's state and progress counters. While the job has not finished, retry_after_ms says when to poll again.\n\nRequired scope: `read`.", "x-required-scope": "read", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" } ], "responses": { "200": { "description": "The job is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "jobs_status_completed_200": { "$ref": "#/components/examples/jobs_status_completed_200" }, "jobs_status_queued_200": { "$ref": "#/components/examples/jobs_status_queued_200" } } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "There is no such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "jobs_404": { "$ref": "#/components/examples/jobs_404" } } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enrich/jobs/{job_id}/results": { "get": { "operationId": "getJobResults", "tags": [ "Jobs" ], "summary": "Page through a job's rows", "description": "This call returns every row in submission order, whatever its status, one page at a time by cursor. A row that is still pending keeps its place in the page. It is also how you collect a defer_live resolve.\n\nRequired scope: `read`.", "x-required-scope": "read", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsPage" }, "examples": { "jobs_results_page1_200": { "$ref": "#/components/examples/jobs_results_page1_200" }, "jobs_results_page2_200": { "$ref": "#/components/examples/jobs_results_page2_200" }, "resolve_progressive_poll_200": { "$ref": "#/components/examples/resolve_progressive_poll_200" }, "resolve_progressive_results_200": { "$ref": "#/components/examples/resolve_progressive_results_200" } } } } }, "400": { "description": "The cursor is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "jobs_results_400_cursor": { "$ref": "#/components/examples/jobs_results_400_cursor" } } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "There is no such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The rows are no longer available (after expires_at).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Gone" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enrich/jobs/{job_id}/errors": { "get": { "operationId": "getJobErrors", "tags": [ "Jobs" ], "summary": "Page through a job's quarantined rows", "description": "This call returns the rows that could not be resolved at all, each with a reason and whether a retry is worthwhile.\n\nRequired scope: `read`.", "x-required-scope": "read", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "A page is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorsPage" }, "examples": { "jobs_errors_200": { "$ref": "#/components/examples/jobs_errors_200" } } } } }, "400": { "description": "The cursor is malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "There is no such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "The rows are no longer available (after expires_at).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Gone" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/enrich/jobs/{job_id}/cancel": { "post": { "operationId": "cancelJob", "tags": [ "Jobs" ], "summary": "Cancel a job", "description": "Rows that have started are delivered; rows that have not started are skipped and never billed. Cancelling a finished job returns it unchanged, so a retried cancel is safe.\n\nRequired scope: `enrich`.", "x-required-scope": "enrich", "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/JobId" } ], "responses": { "200": { "description": "The job is returned in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "jobs_cancel_200": { "$ref": "#/components/examples/jobs_cancel_200" } } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "There is no such job for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "tags": [ "Usage" ], "summary": "Usage by block or by day", "description": "This call returns the counts your invoices are built from, over a date range (by default the last 30 days, at most 366). Until contract prices are set up for the account, it returns counts only.\n\nRequired scope: `read`.", "x-required-scope": "read", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "This is the first day, in YYYY-MM-DD format and UTC.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "This is the last day, inclusive. The default is today.", "schema": { "type": "string", "format": "date" } }, { "name": "granularity", "in": "query", "required": false, "description": "Use block (default) or day.", "schema": { "type": "string", "enum": [ "block", "day" ], "default": "block" } }, { "name": "job_id", "in": "query", "required": false, "description": "Narrow to one job.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "examples": { "usage_day_200": { "$ref": "#/components/examples/usage_day_200" }, "usage_job_200": { "$ref": "#/components/examples/usage_job_200" } } } } }, "400": { "description": "The request contains an invalid date, a from date later than the to date, a range over 366 days, or an unknown granularity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "usage_400_granularity": { "$ref": "#/components/examples/usage_400_granularity" } } } } }, "401": { "description": "The key is missing, malformed, revoked or wrong. The message is the same in every case.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The key lacks the scope this endpoint needs; the message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "job_id is not a job on this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The key sent more requests than its per-minute allowance. Wait for the number of seconds in Retry-After.", "headers": { "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed on Zorro's side. The body carries request_id when available; the X-Request-ID header always does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "zk_live__ or zk_test__", "description": "Authorization: Bearer . Scopes are carried by the key: read (whoami, blocks, job status, results, errors, usage) and enrich (resolve, submit and cancel jobs)." } }, "parameters": { "JobId": { "name": "job_id", "in": "path", "required": true, "description": "The job id from job creation or from a resolve. An id that is not yours, or not an id, answers 404.", "schema": { "type": "string" } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "Use next_cursor from the previous page. Omit it to start.", "schema": { "type": "string" } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "The page size defaults to 100 and is at most 1000. A missing or invalid value uses the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, "IdempotencyKey": { "name": "X-Idempotency-Key", "in": "header", "required": false, "description": "This makes a submit safe to retry. The same key with the same request returns the original job (200); with a different request, 409. It is scoped to the account and kept with the job.", "schema": { "type": "string", "maxLength": 255 } } }, "schemas": { "BlockKey": { "type": "string", "description": "A block in the catalogue. GET /v1/blocks lists all 37 and shows which ones your key may request.", "enum": [ "domain", "related_company_domain", "domain_validation", "nature_of_business", "registered_address", "corporate_owners", "controllers", "charges", "property", "officers", "company_identity", "filing_status", "registry_events", "financials_filed", "ultimate_owner", "employees_filed", "industry", "contacts", "signals", "news_signals", "financials_live", "employees_live", "web_traffic", "web_presence", "technologies", "employees", "planning", "financial_benchmarks", "revenue_estimate", "scores", "funding", "trading_address", "subsidiaries", "firmographics", "comparables", "business_intelligence", "company_summary" ] }, "ReasonCode": { "type": "string", "description": "This lists every reason the API may give on a block envelope, a row or an error body. Any reason outside the published list is returned as `error`. New codes may be added within /v1, so treat a code you do not recognise as `error`.", "enum": [ "error", "not_matched", "no_company_key", "ambiguous_match", "source_unavailable", "resolver_error", "worker_lost", "invalid_company_number", "no_company_identified_on_site", "site_lookup_not_run", "only_related_company_domain", "inheritance_flag_without_a_related_url", "provenance_uncertain_but_validated", "not_found_after_search", "search_unavailable", "no_domain_found", "no_corporate_owner_on_the_register", "owner_has_no_website", "no_psc_data_on_file", "ultimate_owner_not_resolved", "no_address_on_file", "no_charges_data_on_file", "no_property_titles_on_file", "no_officers_on_file", "no_identity_on_file", "no_filing_dates_on_file", "no_registry_dates_on_file", "no_headcount_on_file", "no_employee_estimate_on_file", "not_available_yet", "owner_not_on_file", "domain_name_mismatch", "not_own_site", "validation_not_requested", "site_unreachable", "name_matches_no_address_evidence", "filed_value_implausible", "no_entitlement", "not_for_demo_key", "site_not_readable", "site_blocked", "no_description_on_file", "no_domain_to_read", "site_unreadable", "site_read_unavailable", "no_accounts_filed", "accounts_not_machine_readable", "register_unavailable", "accounts_unreadable", "no_events_in_window", "events_unavailable", "accounts_ocr_unavailable", "contacts_disabled", "contacts_unavailable", "no_people_found", "no_emails_found", "no_domain_for_email", "no_domain_for_phone", "no_email_found", "no_phone_found", "non_uk_only", "shared_number_only", "lookup_failed", "no_planning_applications", "no_planning_on_file", "planning_register_unavailable", "no_scores_on_file", "no_website_to_match", "no_funding_on_record", "enrichment_unavailable", "no_validated_website", "no_address_on_site", "insufficient_corroboration", "conflicting_sources", "postcode_register_unavailable", "google_business_unavailable", "lookups_incomplete", "not_completed", "no_sic_on_file", "no_financials_on_file", "no_modelled_revenue", "no_ratios_to_benchmark", "cohort_too_small", "benchmark_unavailable", "accounts_read_failed", "financials_in_live_filing_only", "bank_income_line_unconfirmed", "bank_profit_line_unconfirmed", "holding_company_no_trading_revenue", "share_capital_as_equity", "equity_implausible_against_balance_sheet", "balance_sheet_breaks_from_adjacent_year", "modelled_implausible_against_filed_turnover", "subsidiary_search_unavailable", "no_profile_on_file", "no_comparables_found", "peer_search_unavailable", "few_comparable_peers", "label_contradicts_filed_sic", "no_business_intelligence_on_file", "site_describes_another_company", "no_summary_on_file", "summary_unavailable", "no_signals_on_file", "no_signals_on_record", "signals_unavailable", "web_profile_not_enabled", "no_web_profile_found", "web_profile_unavailable", "no_web_traffic_on_profile", "no_technologies_on_file", "no_web_presence_on_file", "no_employee_figures_on_file", "web_profile_outside_uk", "no_accounts_reading_on_file", "no_headcount_in_accounts_reading", "no_workforce_on_profile", "org_enrichment_not_held", "website_not_validated", "website_needs_review", "website_unverified", "website_not_verifiable", "accounts_made_up_date_off_reference_date", "bank_no_modelled_turnover", "none_on_register", "first_accounts_not_yet_due", "accounts_overdue", "group_site_prefer_uk_domain", "not_confirmed", "source_busy", "not_looked_up", "owner_website_is_this_companys_own", "no_majority_controller", "dormant_company", "modelled_profit_implausible", "modelled_repeated_across_periods", "ratio_implausible", "accounts_read_no_figures", "sources_disagree", "estimate_input_failed_balance_sheet_check" ], "x-enumDescriptions": { "error": "This is a generic failure with no more specific public reason. Retry once; if it repeats, include the X-Request-ID when contacting support.", "not_matched": "No company was found under the number, name or domain given.", "no_company_key": "The row carried no usable company_number, company_name or domain.", "ambiguous_match": "The name or domain matches more than one live company; the candidates are returned and the row is not billed.", "source_unavailable": "The requested data was unavailable. This says nothing about the company. On a block, retry_suggested is set; a failed row can be resubmitted.", "resolver_error": "The row could not be resolved because of an error on Zorro's side. Resubmit the row.", "worker_lost": "The row was not resolved and can be resubmitted.", "invalid_company_number": "The company_number is not a UK company number (8 characters, for example 07706156 or SC123456). GET /v1/resolve answers 400; in a job, only that row goes to the errors page.", "no_company_identified_on_site": "The website names no active company by number or exact legal name.", "site_lookup_not_run": "The live site lookup for an unknown domain runs only on a single resolve or a job of ten rows or fewer, and this row was in a larger job.", "only_related_company_domain": "The only website on file belongs to a related (owning) company; it is returned under related_company_domain, never as this company's domain.", "inheritance_flag_without_a_related_url": "The website on file may belong to a related company and cannot be confirmed, so it is returned flagged for review.", "provenance_uncertain_but_validated": "The website's provenance was uncertain, but domain_validation on the same row accepted it; the flag is cleared.", "not_found_after_search": "No website was found for the company.", "search_unavailable": "No website result was available. This says nothing about the company; retry_suggested is set.", "no_domain_found": "No website is on file and no live search was asked for.", "no_corporate_owner_on_the_register": "The PSC register names no current corporate owner, so there is no owner to follow.", "owner_has_no_website": "The register names a corporate owner, but no website is on file for it (or its number is not usable).", "no_psc_data_on_file": "No PSC register is on file for the company. This is not the same as a register that names nobody, which returns an empty list.", "ultimate_owner_not_resolved": "The register names a corporate owner, but the chain above it could not be resolved.", "no_address_on_file": "No registered office address is on file for the company.", "no_charges_data_on_file": "No charge information is in the company file.", "no_property_titles_on_file": "No HM Land Registry title matched the company number. This does not prove the company owns no property.", "no_officers_on_file": "No officers are on file for the company.", "no_identity_on_file": "No incorporation date, category or status is on file for the company.", "no_filing_dates_on_file": "No accounts or confirmation statement dates are on file for the company.", "no_registry_dates_on_file": "No register event dates are on file for the company.", "no_headcount_on_file": "No usable filed employee count is on file.", "no_employee_estimate_on_file": "No third-party headcount estimate is on file.", "not_available_yet": "The block is in the catalogue but cannot be answered yet.", "owner_not_on_file": "The register names an owner with no company file (for example a foreign entity), so there is no description to give.", "domain_name_mismatch": "The owner's website shares no distinctive word with the owner's name, so it is returned with that doubt stated.", "not_own_site": "The domain is a register, directory, social or site-builder host (host_type says which): a page about the company, not its own site.", "validation_not_requested": "validation was set to none: the domain comes back unscored and flagged.", "site_unreachable": "The site gave no HTTP response at all (no DNS, connection refused or timeout). Not scored and not rejected.", "name_matches_no_address_evidence": "The company's name is on the site and nothing contradicts it, but no address, postcode, director or phone is shown; the outcome is not lowered below review.", "filed_value_implausible": "Every filed headcount on file is between 0 and 1 and is marked as implausible; the affected years are listed.", "no_entitlement": "The block or option is not enabled for this account.", "not_for_demo_key": "This block is not available to a demo key (named people and paid lookups).", "site_not_readable": "The site answered, but with no readable text (for example a JavaScript stub).", "site_blocked": "The site answered and refused the request (HTTP 401, 403, 429 or 503). retry_suggested is set.", "no_description_on_file": "No written description of the company is on file.", "no_domain_to_read": "The company has no website for the requested live read.", "site_unreadable": "The live site read could not extract usable text from the site.", "site_read_unavailable": "The website could not be read for this request. This says nothing about the company; retry later.", "no_accounts_filed": "The company has no accounts on file at Companies House.", "accounts_not_machine_readable": "The latest accounts were filed on paper or as PDF, with no machine-readable version.", "register_unavailable": "Companies House did not answer the filing request. Retry.", "accounts_unreadable": "The filing was retrieved but could not be read.", "no_events_in_window": "There were no register or company events in the last year.", "events_unavailable": "The event sources could not be read for this request. Retry later.", "accounts_ocr_unavailable": "PDF accounts could not be read for this request. Retry later.", "contacts_disabled": "The contacts block is not available.", "contacts_unavailable": "The contact lookup could not run for this request. Retry later.", "no_people_found": "No decision-maker matching the requested roles was found.", "no_emails_found": "People were found, but no business email was found for any of them.", "no_domain_for_email": "No company website is on file against which to look up an email address.", "no_domain_for_phone": "No company website is on file against which to look up a phone number.", "no_email_found": "The lookup ran and found no email for this person.", "no_phone_found": "The lookup ran and found no phone number for this person.", "non_uk_only": "Only non-UK phone numbers were found; none is returned.", "shared_number_only": "The only number found was already given to another contact in the same answer.", "lookup_failed": "The lookup for this person failed on Zorro's side. Retry later.", "no_planning_applications": "The planning register holds no applications naming the company.", "no_planning_on_file": "No planning answer is on file and none was searched for. This does not prove there are no applications.", "planning_register_unavailable": "The planning register could not be searched.", "no_scores_on_file": "No scores are on file for the company.", "no_website_to_match": "The block matches on the company's own website, and none is on file.", "no_funding_on_record": "The matched record has no funding rounds.", "enrichment_unavailable": "The organisation data could not be read for this request. Retry later.", "no_validated_website": "The company's website was rejected by domain_validation (now or in the last 30 days), so it is not read for an address.", "no_address_on_site": "The site was read and shows no address.", "insufficient_corroboration": "A candidate address was found but not confirmed by an independent source.", "conflicting_sources": "The sources disagree; every candidate is listed for review.", "postcode_register_unavailable": "The postcode register could not be read.", "google_business_unavailable": "google_business was asked for and the listing check could not run.", "lookups_incomplete": "Not every lookup finished; partial is set and the contacts found so far are returned.", "not_completed": "The pending block was not completed because the row ended after a failure or cancellation. The block's status is error, with retry_suggested set.", "no_sic_on_file": "The register has no SIC code for the company (including entries that read \"None Supplied\").", "no_financials_on_file": "No accounts history, figures from PDF accounts or estimated revenue are on file.", "no_modelled_revenue": "No estimated revenue is available for the company.", "no_ratios_to_benchmark": "The company has no ratio from filed figures, or from figures read from PDF accounts, to place among peers.", "cohort_too_small": "The peer cohort contains fewer than twenty companies.", "benchmark_unavailable": "The peer comparison could not be computed for this request. Retry later.", "accounts_read_failed": "financials_live ran in the same request and could not read the accounts, so there is nothing to place among peers yet. Retry later.", "financials_in_live_filing_only": "No accounts history is on file; the figures are in the filing that financials_live read in the same request.", "bank_income_line_unconfirmed": "A bank's turnover figure is withheld: the printed income line it came from is not confirmed.", "bank_profit_line_unconfirmed": "A bank's operating profit figure is withheld: the printed line it came from is not confirmed.", "holding_company_no_trading_revenue": "A holding company, fund or head office is not given an estimated trading revenue.", "share_capital_as_equity": "The equity figure is the share capital line, so it is withheld rather than corrected.", "equity_implausible_against_balance_sheet": "The equity figure cannot be right given the rest of the balance sheet, so it is withheld.", "balance_sheet_breaks_from_adjacent_year": "The balance sheet cannot belong to the same company as the adjacent year's, so it is flagged or withheld, never corrected.", "modelled_implausible_against_filed_turnover": "The filed turnover contradicts the estimated turnover, so the estimate is withheld.", "subsidiary_search_unavailable": "No subsidiary result is available. No empty list is returned because this does not show that the company owns nothing.", "no_profile_on_file": "No company profile field is on file.", "no_comparables_found": "The peer search found no companies.", "peer_search_unavailable": "The peer search could not run.", "few_comparable_peers": "Fewer than three comparable companies were found; those companies are returned flagged.", "label_contradicts_filed_sic": "The industry label sits in a different SIC section from every code the company filed, so it is returned flagged.", "no_business_intelligence_on_file": "No website-derived company information is on file.", "site_describes_another_company": "The site names another company's number and name; the text is returned as flagged.", "no_summary_on_file": "No summary is available for the company.", "summary_unavailable": "The summary could not be produced for this request. Retry later.", "no_signals_on_file": "No event timeline is on file and no lookup was asked for.", "no_signals_on_record": "A lookup ran and found no events.", "signals_unavailable": "The event lookup could not run for this request. Retry later.", "web_profile_not_enabled": "Web profile data is not available.", "no_web_profile_found": "No web profile was found for the company's own site.", "web_profile_unavailable": "The web profile could not be retrieved for this request. Retry later.", "no_web_traffic_on_profile": "A profile was found but carries no traffic figures.", "no_technologies_on_file": "No detected technologies are on file.", "no_web_presence_on_file": "No web presence facts are on file.", "no_employee_figures_on_file": "No headcount figure from any source is on file.", "web_profile_outside_uk": "The answer was built on a profile headquartered outside the UK, so it is returned flagged, with the country in detail.", "no_accounts_reading_on_file": "No figures read from PDF accounts are on file.", "no_headcount_in_accounts_reading": "Figures read from PDF accounts are on file, without a headcount.", "no_workforce_on_profile": "The matched web profile has no workforce figure.", "org_enrichment_not_held": "Organisation data is not on file for the company; this block does not look it up.", "website_not_validated": "The website was rejected, or scored under min_confidence: website-derived data is not served.", "website_needs_review": "The website's outcome is review, at or above min_confidence, so website-derived data is returned with flagged_for_review.", "website_unverified": "There is no verdict on the website (validation was declined, or the check did not finish), so website-derived data is returned with flagged_for_review.", "website_not_verifiable": "The site could not be read for this request, so it could not be checked: website-derived data is withheld.", "accounts_made_up_date_off_reference_date": "The accounts made-up date is not on the company's accounting reference date, so the value is returned flagged, with the expected date beside it.", "bank_no_modelled_turnover": "No estimated turnover is returned for a bank or building society (SIC 64110, 64191, 64192).", "none_on_register": "The Companies House register was checked and holds none.", "first_accounts_not_yet_due": "No accounts are filed and the first accounts are not due yet (detail.first_accounts_due_on).", "accounts_overdue": "No accounts are filed and the register says the due date has passed.", "group_site_prefer_uk_domain": "The site is a group's global one and the company runs a UK site of its own that passes the same check (detail.preferred_domain). The outcome is review, never accept.", "not_confirmed": "There is no value, and the absence could not be confirmed for this request. This says nothing about the company; retry later.", "source_busy": "The requested data was unavailable for this request. retry_suggested is set.", "not_looked_up": "When contacts_lookup=cached_only, no email address or phone number is available for this person.", "owner_website_is_this_companys_own": "The owner's website on file is this company's own website, so it is not returned as the owner's.", "no_majority_controller": "The register names corporate owners and none holds majority control (more than half of the shares or votes, or the right to appoint the board). The largest holder is in detail.largest_holder.", "dormant_company": "The latest accounts filed are dormant accounts, so no estimated trading revenue or profit is returned.", "modelled_profit_implausible": "An estimated profit is withheld if it is larger than the revenue beside it or has no revenue beside it.", "modelled_repeated_across_periods": "An estimated figure repeated unchanged across periods is withheld.", "ratio_implausible": "A ratio whose inputs cannot describe one company's year (a denominator too small, or a value far outside any real range) is withheld.", "accounts_read_no_figures": "The machine-readable filing carried no figure for its latest period.", "sources_disagree": "The two headcount figures on the row differ by a factor of three or more; both are returned as flagged.", "estimate_input_failed_balance_sheet_check": "The estimated figures for that period are withheld because the balance sheet they depend on failed a consistency check." } }, "RowFailureReason": { "type": "string", "description": "Why a whole row failed. Carried by GET /v1/enrich/jobs/{job_id}/errors and by the GET /v1/resolve error bodies.", "enum": [ "error", "not_matched", "no_company_key", "ambiguous_match", "source_unavailable", "resolver_error", "worker_lost", "invalid_company_number" ], "x-enumDescriptions": { "error": "This is a generic failure with no more specific public reason. Retry once; if it repeats, include the X-Request-ID when contacting support.", "not_matched": "No company was found under the number, name or domain given.", "no_company_key": "The row carried no usable company_number, company_name or domain.", "ambiguous_match": "The name or domain matches more than one live company; the candidates are returned and the row is not billed.", "source_unavailable": "The requested data was unavailable. This says nothing about the company. On a block, retry_suggested is set; a failed row can be resubmitted.", "resolver_error": "The row could not be resolved because of an error on Zorro's side. Resubmit the row.", "worker_lost": "The row was not resolved and can be resubmitted.", "invalid_company_number": "The company_number is not a UK company number (8 characters, for example 07706156 or SC123456). GET /v1/resolve answers 400; in a job, only that row goes to the errors page." } }, "BlockStatus": { "type": "string", "enum": [ "available", "not_found", "not_enabled", "error", "pending" ], "description": "`available`: `value` is present. `not_found`: there is no value; `reason` says what kind of absence it is. `not_enabled`: the key may not run this block. `error`: the block failed on Zorro's side, usually with `retry_suggested`. `pending`: a progressive resolve (defer_live) is still working on it." }, "RowStatus": { "type": "string", "enum": [ "pending", "done", "not_found", "error", "skipped" ], "description": "`done`: at least one block is available. `not_found`: the company matched and no block holds a value. `error`: the row could not be resolved (see the errors endpoint). `skipped`: the job was cancelled before this row ran. `pending`: not finished yet." }, "JobStatus": { "type": "string", "enum": [ "queued", "running", "completed", "partially_completed", "cancelling", "cancelled", "failed" ], "description": "A job is `queued` until every row is settled, then `completed`, or `partially_completed` when at least one row failed. A cancel moves it through `cancelling` to `cancelled`. The job is `failed` when it could not finish; `failure_reason` says why. `running` is reserved. The terminal states are `completed`, `partially_completed`, `cancelled` and `failed`." }, "Scope": { "type": "string", "enum": [ "read", "enrich" ] }, "Error": { "type": "object", "description": "The body of every error that is not a field validation error.", "properties": { "detail": { "type": "string", "description": "A human-readable message, or a reason slug on the resolve error bodies. Branch on the HTTP status and on slugs, never on the wording of a message." }, "request_id": { "type": "string", "description": "On a 500: the X-Request-ID of the failed request, to quote to support." }, "documentation": { "type": "string", "description": "On a 404 for a path that does not exist: where the documentation is. Absent from a 404 raised by an endpoint that does exist, such as a job id that is not yours." }, "openapi": { "type": "string", "description": "On the same 404: the path this description is served from." } }, "required": [ "detail" ], "additionalProperties": true }, "FieldErrors": { "type": "object", "description": "A 400 from input validation: each invalid field maps to a list of messages, nested by row number or option name, e.g. {\"options\": {\"min_confidence\": [\"Ensure this value is less than or equal to 1.0.\"]}} or {\"rows\": {\"0\": {\"non_field_errors\": [\"...\"]}}}. The 413 row-count refusal uses the same shape under `rows`.", "minProperties": 1, "additionalProperties": true }, "NotEnabledError": { "type": "object", "description": "403 when every block asked for is outside the key's entitlement, or a premium option is not enabled. A request that mixes enabled and not-enabled blocks is not refused: it answers 200 with a `blocks_not_enabled` warning.", "properties": { "detail": { "type": "string", "description": "Names the refused blocks or options." }, "blocks": { "type": "object", "description": "Present when blocks were refused: each refused block with status not_enabled and a reason (no_entitlement, or not_for_demo_key).", "additionalProperties": { "type": "object", "properties": { "status": { "const": "not_enabled" }, "reason": { "$ref": "#/components/schemas/ReasonCode" } }, "required": [ "status", "reason" ], "additionalProperties": true } }, "options": { "type": "object", "description": "Present when a premium option was refused on job creation (web_search).", "additionalProperties": { "type": "object", "properties": { "status": { "const": "not_enabled" }, "reason": { "$ref": "#/components/schemas/ReasonCode" } }, "required": [ "status", "reason" ], "additionalProperties": true } } }, "required": [ "detail" ], "additionalProperties": true }, "ResolveNotFound": { "type": "object", "description": "404 from GET /v1/resolve: no company matched.", "properties": { "detail": { "const": "not_matched" }, "reason": { "type": "string", "description": "For a lookup by domain: why the domain matched no company. One of not_own_site, no_company_identified_on_site, site_unreachable, site_blocked or site_not_readable." }, "host_type": { "type": "string", "enum": [ "register", "directory", "social", "site_builder" ], "description": "With reason not_own_site: what kind of host it is." }, "site_lookup": { "$ref": "#/components/schemas/SiteLookup" } }, "required": [ "detail" ], "additionalProperties": true }, "AmbiguousMatch": { "type": "object", "properties": { "detail": { "const": "ambiguous_match" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" }, "description": "The live companies the name or domain matched. Retry with one company_number." } }, "required": [ "detail", "candidates" ], "additionalProperties": true }, "Candidate": { "type": "object", "properties": { "company_number": { "type": "string", "description": "Companies House number." }, "company_name": { "anyOf": [ { "type": "string", "description": "Registered name." }, { "type": "null" } ] } }, "required": [ "company_number" ], "additionalProperties": true }, "SiteLookup": { "type": "object", "description": "For a domain with no company on file: what its landing and legal pages gave.", "properties": { "reason": { "type": "string", "description": "Why the site named no company, or ambiguous_match." }, "domain": { "type": "string", "description": "The domain as normalised." }, "final_url": { "anyOf": [ { "type": "string", "description": "Where the read landed after redirects." }, { "type": "null" } ] }, "pages_read": { "type": "array", "items": {}, "description": "The pages read." } }, "additionalProperties": true }, "Gone": { "type": "object", "description": "410 on results or errors of a job whose rows are no longer available (after expires_at). The job itself still answers GET /v1/enrich/jobs/{job_id}.", "properties": { "detail": { "type": "string", "description": "Says the rows are no longer available." }, "job_id": { "type": "string", "format": "uuid" }, "purged_at": { "type": "string", "format": "date-time" } }, "required": [ "detail", "job_id", "purged_at" ], "additionalProperties": true }, "WhoAmI": { "type": "object", "properties": { "key_id": { "type": "string", "description": "The public part of the key. Safe to log and to quote to support.", "pattern": "^[a-z2-9]{12}$" }, "name": { "type": "string", "description": "The label the key was minted with." }, "environment": { "type": "string", "enum": [ "live", "test" ], "description": "A label on the key (zk_live_ or zk_test_). A test key reads the same data and is billed the same way; it is not a sandbox." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "account": { "type": "object", "properties": { "id": { "type": "integer", "description": "The account the key acts as." }, "email": { "type": "string", "description": "The account's email." } }, "required": [ "id", "email" ], "additionalProperties": true }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockAccess" }, "description": "Every block in catalog order with its availability for this key and its tier." }, "blocks_enabled_count": { "type": "integer", "description": "How many blocks this key may request." }, "blocks_total": { "type": "integer", "description": "How many blocks the catalog has." }, "limits": { "$ref": "#/components/schemas/KeyLimits" }, "docs": { "type": "object", "properties": { "url": { "type": "string", "description": "This documentation." }, "openapi": { "type": "string", "description": "Where this description is served, as a path on the API host." }, "catalog": { "type": "string", "description": "Where the full catalogue is." } }, "required": [ "url", "openapi", "catalog" ], "additionalProperties": true } }, "required": [ "key_id", "name", "environment", "scopes", "account", "blocks", "blocks_enabled_count", "blocks_total", "limits", "docs" ], "additionalProperties": true }, "BlockAccess": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/BlockKey" }, "availability": { "type": "string", "enum": [ "available", "not_enabled" ] }, "tier": { "type": "string", "enum": [ "core", "premium" ] } }, "required": [ "key", "availability", "tier" ], "additionalProperties": true }, "KeyLimits": { "type": "object", "properties": { "max_rows_per_job": { "type": "integer", "description": "The most rows one job may carry for this key." }, "max_rows_per_job_source": { "type": "string", "enum": [ "key", "default" ], "description": "`key` when this key has its own, lower cap; `default` when the global cap applies." }, "rate_limits": { "type": "object", "properties": { "requests_per_minute": { "anyOf": [ { "type": "integer", "description": "Every endpoint, per key." }, { "type": "null" } ] }, "resolve_per_minute": { "anyOf": [ { "type": "integer", "description": "GET /v1/resolve, per key." }, { "type": "null" } ] } }, "required": [ "requests_per_minute", "resolve_per_minute" ], "additionalProperties": true }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "Always null today: keys do not expire." }, { "type": "null" } ] } }, "required": [ "max_rows_per_job", "max_rows_per_job_source", "rate_limits", "expires_at" ], "additionalProperties": true }, "BlockCatalog": { "type": "object", "properties": { "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEntry" } }, "available": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" }, "description": "The blocks this key may request, in catalog order." }, "confidence": { "type": "object", "additionalProperties": true, "description": "How to read `confidence`: the scale, the domain_validation routing cuts (accept / review / reject), what the number is made of and what it is not." }, "validation_modes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "What each validation mode adds: none, rules, live, officers and ai." }, "discovery_options": { "type": "object", "additionalProperties": { "type": "string" } }, "contact_options": { "type": "object", "additionalProperties": { "type": "string" } }, "latency_classes": { "type": "object", "properties": { "instant": { "type": "string" }, "live": { "type": "string" } }, "required": [ "instant", "live" ], "additionalProperties": true }, "premium_options": { "type": "object", "additionalProperties": { "type": "object", "properties": { "description": { "type": "string" }, "what_it_buys": { "type": "string" }, "default": { "type": "boolean" }, "billable": { "type": "boolean" }, "availability": { "type": "string", "enum": [ "available", "not_enabled" ] } }, "required": [ "description", "what_it_buys", "default", "billable", "availability" ], "additionalProperties": true } } }, "required": [ "blocks", "available", "confidence", "validation_modes", "discovery_options", "contact_options", "latency_classes", "premium_options" ], "additionalProperties": true }, "CatalogEntry": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/BlockKey" }, "description": { "type": "string", "description": "What the block returns." }, "source": { "type": "string", "description": "Where the data comes from, in words." }, "availability": { "type": "string", "enum": [ "available", "not_enabled" ], "description": "For the calling key." }, "tier": { "type": "string", "enum": [ "core", "premium" ] }, "experimental": { "type": "boolean", "description": "Refused by default and switched on per account." }, "billable": { "type": "boolean", "description": "Charged when it delivers a value." }, "page_fields": { "type": "array", "items": { "type": "string" }, "description": "The field names on getzorro.ai/api this block delivers." }, "latency": { "type": "string", "enum": [ "instant", "live" ] }, "latency_note": { "type": "string", "description": "When the latency class changes for a company." }, "live_deadline_s": { "type": "number", "description": "Seconds this block may take in a progressive answer; past it the block answers `error` with `source_busy`." }, "website_gate": { "type": "string", "description": "For blocks built from the company's website: how the website verdict gates them." }, "coverage": { "type": "number", "description": "The catalog's coverage figure for the block, 0 to 1." }, "coverage_measured_on": { "type": "string", "description": "The date of the coverage figure. YYYY-MM-DD." } }, "required": [ "key", "description", "source", "availability", "tier", "experimental", "billable", "page_fields", "latency" ], "additionalProperties": true }, "BlockEnvelope": { "type": "object", "description": "Every block on every row comes back in this envelope, from GET /v1/resolve and from a job alike. Keys that do not apply are absent, not null. New keys may be added within /v1.", "properties": { "status": { "$ref": "#/components/schemas/BlockStatus" }, "value": { "description": "This is present only when status is available. Its shape depends on the block; see the block schemas." }, "source": { "type": "string", "description": "Where the value came from: `companies_house`, `companies_house_live`, `companies_house_psc`, `companies_house_accounts`, `companies_house_accounts_ocr`, `zorro_modelled_from_filings`, `hm_land_registry`, `cache`, `live_site_read`, `zorro_validator`, `zorro_from_website`, `zorro_peer_model`, `third_party_profile` and others named in the catalogue." }, "as_of": { "type": "string", "description": "The date of the information: a date (YYYY-MM-DD), a year (YYYY) for a filing year, or the time the value was checked. Absent when no date exists." }, "confidence": { "type": "number", "description": "A number from 0 to 1, present only on blocks that produce one. The scale differs between blocks; see `confidence` in GET /v1/blocks.", "minimum": 0, "maximum": 1 }, "flagged_for_review": { "type": "boolean", "description": "When `true`, read `reason` before relying on the value. The value is still returned." }, "reason": { "$ref": "#/components/schemas/ReasonCode" }, "detail": { "$ref": "#/components/schemas/EnvelopeDetail" }, "partial": { "type": "object", "additionalProperties": true, "description": "For not_found or error, this contains available information, such as the domain and whether the site answered." }, "retry_suggested": { "type": "boolean", "description": "This indicates that the block was not completed or confirmed for the request." }, "derived": { "type": "boolean", "description": "The value is a Zorro-derived value rather than a filed fact." }, "derived_from": { "type": "string", "enum": [ "company_website_short", "company_website_detailed", "search_description", "company_website", "zorro_enrichment" ], "description": "For nature_of_business, this identifies the associated description." }, "contains_modelled": { "type": "boolean", "description": "financials_filed: part of the value is modelled (under `modelled`, or with a `*_basis` of `modelled`)." }, "contains_ocr_read": { "type": "boolean", "description": "For financials_filed, part of the value was read from PDF accounts." }, "contains_derived": { "type": "boolean", "description": "For financials_filed, ratios computed from filed figures or figures read from PDF accounts are present." }, "host_type": { "type": "string", "enum": [ "register", "directory", "social", "site_builder" ] }, "verification_profile": { "type": "string", "description": "For domain, this contains website verification information." }, "final_url": { "type": "string", "description": "domain: the address actually read after redirects, when a block on the row opened the site." }, "affected_years": { "type": "array", "items": { "type": "string" }, "description": "For employees_filed with filed_value_implausible, these are the years whose filed figures were refused." } }, "required": [ "status" ], "additionalProperties": true }, "EnvelopeDetail": { "type": "object", "description": "How the answer was built. Blocks can add their own keys.", "properties": { "freshness": { "$ref": "#/components/schemas/Freshness" }, "website_verdict": { "$ref": "#/components/schemas/WebsiteVerdict" }, "evidence": { "type": "object", "additionalProperties": true, "description": "domain_validation: where on the site each hard match and the name were found (url and snippet)." }, "preferred_domain": { "type": "string", "description": "domain_validation with group_site_prefer_uk_domain: the UK domain that passes." }, "redirected_from": { "type": "string", "description": "The domain on file that forwards to the served one." }, "items_returned": { "type": "integer", "description": "Rows returned when the register holds more." }, "items_on_register": { "type": "integer", "description": "Rows the register holds." }, "first_accounts_due_on": { "type": "string", "description": "No accounts filed yet: when the first are due. YYYY-MM-DD." }, "extraction_confidence": { "type": "number", "description": "nature_of_business: the confidence reported for the description." }, "markets_stated": { "$ref": "#/components/schemas/MarketsStated" } }, "additionalProperties": true }, "MarketsStated": { "type": "object", "description": "nature_of_business.detail.markets_stated, an experimental field. The countries the company's own website states it serves (country sites or pages, shipping lists, offices, customers, currencies or languages offered), each with a basis. scope is worldwide when the site says it serves customers worldwide, and countries is then empty. This is not trade data. Absent when the site states none.", "properties": { "experimental": { "type": "boolean", "description": "Always `true` while this field is experimental." }, "scope": { "type": "string", "enum": [ "countries", "worldwide" ], "description": "`worldwide` when the site says it serves customers worldwide; `countries` is then empty." }, "countries": { "type": "array", "maxItems": 15, "items": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code." }, "name": { "type": "string", "description": "The country name." }, "basis": { "type": "string", "enum": [ "country_site", "shipping", "office", "customers", "currency_or_language" ], "description": "What the site states: a country site or page, shipping there, an office there, customers there, or a currency or language offered for that country." } }, "required": [ "country", "name", "basis" ], "additionalProperties": true }, "description": "The countries named on the site, at most 15." } }, "required": [ "scope", "countries" ], "additionalProperties": true }, "Freshness": { "type": "object", "description": "How current a register answer is.", "properties": { "checked_live": { "type": "boolean", "description": "`true`: Companies House was checked for this request. `false`: the answer was not checked live for this request; `as_of` gives the date of the information." }, "checked_at": { "type": "string", "format": "date-time", "description": "When the live check was made. Present only when `checked_live` is `true`." } }, "required": [ "checked_live" ], "additionalProperties": true }, "WebsiteVerdict": { "type": "object", "description": "The verdict on the company's website a website-derived block was built on.", "properties": { "domain": { "type": "string", "description": "The website the verdict is about." }, "outcome": { "anyOf": [ { "type": "string", "enum": [ "accept", "review", "reject" ] }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "number", "description": "domain_validation score, 0 to 100." }, { "type": "null" } ] }, "confidence": { "anyOf": [ { "type": "number", "description": "domain_validation confidence, 0 to 1." }, { "type": "null" } ] }, "checked_at": { "type": "string", "description": "When the verdict was reached." }, "basis": { "type": "string", "description": "Why there is no verdict." }, "auto_run": { "type": "boolean", "description": "The check was run for this block without being requested, and left out of the response." }, "served": { "type": "boolean", "description": "Whether website data was served on this verdict." } }, "required": [ "domain", "auto_run" ], "additionalProperties": true }, "CompanyIdentityValue": { "type": "object", "description": "company_identity.value", "properties": { "incorporated_on": { "type": "string", "description": "Incorporation date. YYYY-MM-DD." }, "company_category": { "type": "string", "description": "This is the register's category, e.g. Private Limited Company." }, "country_of_origin": { "type": "string", "description": "This is shown as filed." }, "legal_form": { "type": "string" }, "company_status": { "type": "string", "description": "The register's label verbatim: Active, Dissolved, Liquidation, Active - Proposal to Strike off, ..." }, "status_group": { "type": "string", "enum": [ "active", "proposal_to_strike_off", "insolvency", "dissolved", "closed", "other" ] }, "dissolved_on": { "type": "string", "description": "Where a dissolution date is on file. YYYY-MM-DD." }, "trading_name": { "type": "string", "description": "From a company profile field, not Companies House (which records none)." }, "trading_name_source": { "type": "string", "const": "third_party_profile" }, "other_trading_names": { "type": "array", "items": { "type": "string" }, "description": "Further distinct trading names from the same profile fields." }, "trading_name_withheld": { "type": "string", "description": "Why a profile name was not served (it names another organisation)." }, "previous_names": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "A former registered name." }, "changed_on_as_filed": { "type": "string", "description": "The change date exactly as the source holds it (day-first, DD/MM/YYYY). Not reformatted." } }, "required": [ "name" ], "additionalProperties": true } } }, "additionalProperties": true }, "RegisteredAddressValue": { "type": "object", "description": "registered_address.value: only the lines the register holds.", "properties": { "address_line_1": { "type": "string" }, "address_line_2": { "type": "string" }, "locality": { "type": "string", "description": "This is the post town." }, "region": { "type": "string", "description": "This is the county." }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "po_box": { "type": "string" }, "care_of": { "type": "string" } }, "additionalProperties": true }, "Officer": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "description": "Director, Secretary, Corporate Secretary, LLP Member ..." }, { "type": "null" } ] }, "appointed_on": { "anyOf": [ { "type": "string", "description": "Appointment date. YYYY-MM-DD." }, { "type": "null" } ] }, "resigned_on": { "anyOf": [ { "type": "string", "description": "former[] only. YYYY-MM-DD." }, { "type": "null" } ] }, "nationality": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_of_residence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occupation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "person_number": { "type": "string", "description": "The register's identifier for the officer." }, "person_key": { "type": "string", "description": "First eight digits of a 12-digit person number, shared by one person's appointments." }, "date_of_birth": { "$ref": "#/components/schemas/MonthYear" }, "is_corporate": { "type": "boolean", "description": "The officer is a company." } }, "required": [ "name" ], "additionalProperties": true }, "MonthYear": { "type": "object", "description": "Month and year only, as Companies House publishes. Never the day.", "properties": { "month": { "type": "integer", "description": "1-12", "minimum": 1, "maximum": 12 }, "year": { "type": "integer", "description": "Four digits." } }, "additionalProperties": true }, "OfficersValue": { "type": "object", "description": "officers.value. as_of says how current the list is.", "properties": { "total": { "anyOf": [ { "type": "integer", "description": "This is the number of officers ever appointed." }, { "type": "null" } ] }, "active": { "anyOf": [ { "type": "integer", "description": "This is the number of current officers." }, { "type": "null" } ] }, "resigned": { "type": "integer", "description": "This is the number of resigned officers." }, "current": { "type": "array", "items": { "$ref": "#/components/schemas/Officer" }, "description": "Current officers, directors first, at most 25." }, "former": { "type": "array", "items": { "$ref": "#/components/schemas/Officer" }, "description": "Resigned officers, newest resignation first, at most 50." }, "former_truncated": { "type": "boolean", "description": "former[] was cut at 50." }, "ages": { "type": "object", "properties": { "average": { "type": "number", "description": "Years." }, "youngest": { "type": "number", "description": "Years." }, "oldest": { "type": "number", "description": "Years." } }, "additionalProperties": true } }, "additionalProperties": true }, "Controller": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "person", "statement" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_number": { "type": "string", "description": "Companies and legal entities, where a usable number is filed." }, "country_registered": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationality": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country_of_residence": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "date_of_birth": { "anyOf": [ { "$ref": "#/components/schemas/MonthYear" }, { "type": "null" } ] }, "natures_of_control": { "type": "array", "items": { "type": "string" }, "description": "As filed, e.g. ownership-of-shares-75-to-100-percent." }, "notified_on": { "anyOf": [ { "type": "string", "description": "When the register was notified. YYYY-MM-DD." }, { "type": "null" } ] }, "statement": { "anyOf": [ { "type": "string", "description": "type statement: the filed wording, or null." }, { "type": "null" } ] }, "ceased_on": { "anyOf": [ { "type": "string", "description": "ceased_controllers[] only. YYYY-MM-DD." }, { "type": "null" } ] } }, "required": [ "type" ], "additionalProperties": true }, "ControllersValue": { "type": "object", "description": "controllers.value", "properties": { "controllers": { "type": "array", "items": { "$ref": "#/components/schemas/Controller" }, "description": "Live PSC entries; ceased ones are excluded." }, "has_corporate_owner": { "type": "boolean", "description": "A company or legal entity is among the live entries." }, "control": { "type": "object", "properties": { "has_corporate_controller": { "type": "boolean" }, "has_individual_controller": { "type": "boolean" }, "no_controller_on_register": { "type": "boolean", "description": "Neither a company nor a person is named." }, "statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "statement_notified_on": { "type": "string", "description": "A live statement entry exists. YYYY-MM-DD." } }, "required": [ "has_corporate_controller", "has_individual_controller", "no_controller_on_register", "statement" ], "additionalProperties": true }, "ceased_controllers": { "type": "array", "items": { "$ref": "#/components/schemas/Controller" }, "description": "Ceased entries, newest first, each with ceased_on." } }, "required": [ "controllers", "has_corporate_owner", "control", "ceased_controllers" ], "additionalProperties": true }, "CorporateOwnersValue": { "type": "object", "description": "corporate_owners.value. Each owner may carry its own nature_of_business envelope (what the owner does).", "properties": { "has_corporate_owner": { "type": "boolean" }, "owners": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_number": { "type": "string", "description": "As filed, where usable." }, "country_registered": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "natures_of_control": { "type": "array", "items": { "type": "string" }, "description": "This is shown as filed." }, "notified_on": { "anyOf": [ { "type": "string", "description": "YYYY-MM-DD." }, { "type": "null" } ] }, "nature_of_business": { "$ref": "#/components/schemas/BlockEnvelope" } }, "additionalProperties": true } } }, "required": [ "has_corporate_owner", "owners" ], "additionalProperties": true }, "UltimateOwnerValue": { "type": "object", "description": "ultimate_owner.value", "properties": { "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "depth": { "type": "integer", "description": "This is the number of steps from this company to the top." }, "resolved_by": { "type": "string", "description": "This is the resolution category for the top of the chain." }, "chain": { "type": "array", "items": { "type": "object", "properties": { "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": true } } }, "additionalProperties": true }, "Charge": { "type": "object", "properties": { "charge_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "description": "outstanding, satisfied, part-satisfied ... as classified." }, { "type": "null" } ] }, "created_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "registered_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "satisfied_on": { "type": "string", "description": "Where satisfied. YYYY-MM-DD." }, "persons_entitled": { "type": "array", "items": { "type": "string" }, "description": "Holders verbatim, capacity included (\", AS SECURITY AGENT\")." }, "type": { "type": "string", "description": "The filed description, e.g. DEBENTURE." }, "particulars": { "type": "string", "description": "Particulars as filed." }, "contains": { "type": "array", "items": { "type": "string", "enum": [ "fixed_charge", "floating_charge", "floating_charge_covers_all", "negative_pledge" ] } }, "secured_on": { "type": "string", "description": "General description of the property, where filed." }, "amount_secured": { "description": "This is shown as filed." } }, "additionalProperties": true }, "ChargesValue": { "type": "object", "description": "charges.value. as_of is the latest registration date.", "properties": { "outstanding_count": { "type": "integer", "description": "Counted from the charge records." }, "satisfied_count": { "type": "integer" }, "total_count": { "type": "integer" }, "unclassified_count": { "type": "integer", "description": "This is the number of charges with no classification." }, "holders": { "type": "array", "items": { "type": "string" }, "description": "These are the distinct holders of outstanding charges, shown verbatim." }, "charges": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" }, "description": "Outstanding charges." }, "satisfied_charges": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" }, "description": "Newest satisfaction first, at most 50." }, "satisfied_truncated": { "type": "boolean" }, "past_holders": { "type": "array", "items": { "type": "string" }, "description": "These are the holders of satisfied charges." }, "latest_created_on": { "type": "string" }, "latest_satisfied_on": { "type": "string" } }, "required": [ "outstanding_count", "satisfied_count", "total_count", "holders", "charges" ], "additionalProperties": true }, "FilingStatusValue": { "type": "object", "description": "filing_status.value", "properties": { "accounts_last_made_up_on": { "type": "string", "description": "YYYY-MM-DD." }, "accounts_next_due_on": { "type": "string", "description": "YYYY-MM-DD." }, "accounts_next_made_up_to": { "type": "string", "description": "YYYY-MM-DD." }, "accounts_category": { "type": "string", "description": "This is the register's accounts category, e.g. FULL, SMALL, MICRO ENTITY, NO ACCOUNTS FILED." }, "accounts_overdue": { "type": "boolean", "description": "The register's overdue flag." }, "confirmation_statement_last_made_up_on": { "type": "string", "description": "YYYY-MM-DD." }, "confirmation_statement_next_due_on": { "type": "string", "description": "YYYY-MM-DD." }, "confirmation_statement_overdue": { "type": "boolean", "description": "The register's overdue flag." }, "accounts_last_made_up_on_expected": { "type": "object", "description": "This is given with reason accounts_made_up_date_off_reference_date and contains the date implied by the accounting reference date. The date above is left unchanged.", "properties": { "date": { "type": "string", "format": "date" }, "rule": { "type": "string" }, "note": { "type": "string" } }, "additionalProperties": true }, "corrections": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous_value": { "type": "string" }, "rule": { "type": "string" } }, "additionalProperties": true }, "description": "This is a corrected due date because accounts on the register had already met the earlier date." } }, "additionalProperties": true }, "RegistryEventsValue": { "type": "object", "description": "registry_events.value: each date absent when nothing of that kind is on file. as_of is the latest of them.", "properties": { "officer_appointed_on": { "type": "string", "description": "YYYY-MM-DD." }, "officer_resigned_on": { "type": "string", "description": "YYYY-MM-DD." }, "officer_details_changed_on": { "type": "string", "description": "YYYY-MM-DD." }, "psc_added_on": { "type": "string", "description": "YYYY-MM-DD." }, "psc_ceased_on": { "type": "string", "description": "YYYY-MM-DD." }, "psc_changed_on": { "type": "string", "description": "YYYY-MM-DD." }, "shares_allotted_on": { "type": "string", "description": "YYYY-MM-DD." } }, "additionalProperties": true }, "FinancialPeriod": { "type": "object", "properties": { "year": { "type": "string", "description": "The year key." }, "period_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "period_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "period_end_basis": { "type": "string", "description": "year_key_only when no date is on file; ocr_read when read from the filing." }, "filed": { "type": "object", "additionalProperties": true, "description": "Figures as filed (turnover and profit_loss only where a P&L was filed; net_worth and working_capital alias the filed figures)." }, "modelled": { "type": "object", "additionalProperties": true, "description": "Modelled turnover, profit_loss, profit_margin_pct, turnover_growth_pct." }, "ocr_read": { "type": "object", "additionalProperties": true, "description": "Figures read from PDF accounts: page and confidence per field, always flagged." }, "derived": { "type": "object", "additionalProperties": true, "description": "Ratios from filed or read figures, each with formula, basis and inputs." }, "not_derivable": { "type": "object", "additionalProperties": true }, "filed_withheld": { "type": "object", "additionalProperties": true }, "modelled_withheld": { "type": "string" }, "flagged_for_review": { "type": "boolean" } }, "required": [ "year", "filed", "modelled" ], "additionalProperties": true }, "FinancialsFiledValue": { "type": "object", "description": "financials_filed.value", "properties": { "revenue_gbp": { "type": "number", "description": "This is the newest filed or ocr_read turnover, or the modelled turnover only when nothing was filed. Check revenue_basis." }, "revenue_basis": { "type": "string", "description": "The value is filed, ocr_read or modelled." }, "revenue_period_end": { "type": "string" }, "profit_loss_gbp": { "type": "number", "description": "This is the headline profit and follows the same rule." }, "profit_loss_basis": { "type": "string" }, "profit_loss_period_end": { "type": "string" }, "turnover_change_pct": { "type": "number" }, "turnover_change_basis": { "type": "string" }, "turnover_change_period_end": { "type": "string" }, "best_turnover_growth_pct": { "type": "number" }, "best_turnover_growth_basis": { "type": "string" }, "profit_margin_stable": { "type": "boolean" }, "filed_revenue": { "type": "object", "additionalProperties": true }, "filed_profit_loss": { "type": "object", "additionalProperties": true }, "modelled_profit_loss": { "type": "object", "additionalProperties": true }, "modelled_revenue": { "type": "object", "additionalProperties": true, "description": "This is the modelled revenue with its band." }, "modelled_revenue_withheld": { "$ref": "#/components/schemas/ReasonCode" }, "turnover_definition": { "type": "object", "additionalProperties": true }, "withheld": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "These are withheld figures, each with period_end, side, field and reason." }, "years": { "type": "integer", "description": "This is the number of periods." }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialPeriod" }, "description": "Newest first." } }, "additionalProperties": true }, "DomainValidationValue": { "type": "object", "description": "domain_validation.value. With validation=none only domain is present.", "properties": { "domain": { "type": "string", "description": "This is the website checked or, after a passing redirect, the final domain." }, "dns_resolves": { "anyOf": [ { "type": "boolean", "description": "In live mode, the name resolves. null means that the check could not be completed." }, { "type": "null" } ] }, "email_deliverable": { "anyOf": [ { "type": "boolean", "description": "In live mode, the domain accepts mail. null means that the check could not be completed." }, { "type": "null" } ] }, "site_live": { "anyOf": [ { "type": "boolean", "description": "In live mode, the site answered over HTTP(S)." }, { "type": "null" } ] }, "http_status": { "anyOf": [ { "type": "integer", "description": "This is the HTTP status returned for the website." }, { "type": "null" } ] }, "final_url": { "type": "string", "description": "This is the final URL after redirects." }, "final_domain": { "type": "string", "description": "The domain that the domain on file forwards to." }, "note": { "type": "string" }, "director_check": { "type": "string", "enum": [ "companies_house", "source_busy" ], "description": "This identifies the source of the director check." }, "score": { "type": "integer", "description": "This is the score, with a maximum of 100.", "minimum": 0, "maximum": 100 }, "outcome": { "type": "string", "enum": [ "accept", "review", "reject" ], "description": "The verdict. accept: score >= 50 with a hard match and no objection. review: 40–49, or >= 50 without a hard match. reject: under 40." }, "reason": { "type": "string", "description": "name_matches_no_address_evidence when only the name tied the site to the company." }, "checks": { "type": "object", "additionalProperties": true, "description": "This object may contain legal_name_exact, business_name, same_postcode, similar_postcode, city_match, county_match, address_match, director_match, company_number, other_company_number, foreign_registration, uk_domain, phone_present, generic_platform and parked." }, "contributions": { "type": "object", "additionalProperties": { "type": "number" }, "description": "This object contains the contribution associated with each check." }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "These are short notes about the checks." }, "ai_outcome": { "type": "string", "enum": [ "pass", "fail" ], "description": "ai mode: reported beside the score; it does not change the score." }, "ai_reason": { "type": "string" } }, "required": [ "domain" ], "additionalProperties": true }, "NatureOfBusinessValue": { "type": "object", "description": "nature_of_business.value: a description of what the company does, written from its website.", "properties": { "one_liner": { "type": "string", "description": "This is a short description." }, "product_service": { "type": "string", "description": "This describes the offering in detail." } }, "additionalProperties": true }, "IndustryValue": { "type": "object", "description": "industry.value", "properties": { "sic": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "scheme": { "type": "string", "enum": [ "sic_2007", "sic_2003" ] }, "is_primary": { "type": "boolean" } }, "required": [ "code", "is_primary" ], "additionalProperties": true } }, "label": { "type": "string", "description": "This is a plain-English industry label." }, "label_source": { "type": "string", "enum": [ "sic", "nace", "unknown", "other" ] }, "nace": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "from_sic": { "type": "string" }, "description": { "type": "string" } }, "required": [ "code", "from_sic" ], "additionalProperties": true } }, "tags": { "type": "object", "description": "These are activity tags from the website; they are withheld when the website is not validated.", "properties": { "level_1": { "type": "array", "items": { "type": "string" }, "description": "" }, "level_2": { "type": "array", "items": { "type": "string" }, "description": "" }, "level_3": { "type": "array", "items": { "type": "string" }, "description": "" } }, "additionalProperties": true }, "tags_source": { "type": "string", "const": "zorro_from_website" }, "sic_is_generic": { "type": "boolean", "description": "None of the filed codes names a trade (dormant, holding, n.e.c.)." }, "declared_activity": { "type": "string", "description": "This is the nature_of_business one-liner for comparison when that block is on the same row." } }, "required": [ "sic", "sic_is_generic" ], "additionalProperties": true }, "SubsidiariesValue": { "type": "object", "description": "subsidiaries.value: direct holdings only.", "properties": { "subsidiaries": { "type": "array", "items": { "type": "object", "properties": { "company_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "natures_of_control": { "type": "array", "items": { "type": "string" }, "description": "" }, "ownership_band": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notified_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "matched_on": { "type": "string", "enum": [ "registration_number", "name" ] } }, "additionalProperties": true } }, "count": { "type": "integer" }, "active_count": { "type": "integer" }, "truncated": { "type": "boolean", "description": "This is true when there are more than 100 matching companies." } }, "required": [ "subsidiaries", "count", "active_count" ], "additionalProperties": true }, "PropertyValue": { "type": "object", "description": "property.value (HM Land Registry, England and Wales).", "properties": { "title_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "total_price_paid_gbp": { "type": "number", "description": "The sum paid for the titles when bought. Not a valuation." }, "tenure": { "type": "array", "items": { "type": "string" }, "description": "" }, "postcodes": { "type": "array", "items": { "type": "string" }, "description": "" }, "addresses": { "type": "array", "items": { "type": "string" }, "description": "" } }, "additionalProperties": true }, "RelatedCompanyDomainValue": { "type": "object", "properties": { "domain": { "type": "string" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_number": { "type": "string" } }, "required": [ "domain" ], "additionalProperties": true }, "ContactsValue": { "type": "object", "additionalProperties": true, "description": "contacts.value: people with role, email and status. Personal data; see the catalog description." }, "RowBlocks": { "type": "object", "description": "One envelope per requested block, keyed by block.", "properties": { "company_identity": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/CompanyIdentityValue" } } } ] }, "registered_address": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/RegisteredAddressValue" } } } ] }, "officers": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/OfficersValue" } } } ] }, "controllers": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/ControllersValue" } } } ] }, "corporate_owners": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/CorporateOwnersValue" } } } ] }, "ultimate_owner": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/UltimateOwnerValue" } } } ] }, "industry": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/IndustryValue" } } } ] }, "charges": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/ChargesValue" } } } ] }, "filing_status": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/FilingStatusValue" } } } ] }, "registry_events": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/RegistryEventsValue" } } } ] }, "financials_filed": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/FinancialsFiledValue" } } } ] }, "employees_filed": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "type": "integer", "description": "Average employees as filed; as_of is the year." } } } ] }, "domain": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "type": "string", "description": "The registrable domain." } } } ] }, "domain_validation": { "description": "Core.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/DomainValidationValue" } } } ] }, "nature_of_business": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/NatureOfBusinessValue" } } } ] }, "subsidiaries": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/SubsidiariesValue" } } } ] }, "property": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/PropertyValue" } } } ] }, "related_company_domain": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/RelatedCompanyDomainValue" } } } ] }, "contacts": { "description": "Premium.", "allOf": [ { "$ref": "#/components/schemas/BlockEnvelope" }, { "type": "object", "properties": { "value": { "$ref": "#/components/schemas/ContactsValue" } } } ] } }, "additionalProperties": { "$ref": "#/components/schemas/BlockEnvelope" } }, "Matched": { "type": "object", "properties": { "company_number": { "type": "string" }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "match_confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "matched_on": { "anyOf": [ { "type": "string", "enum": [ "company_number", "company_name", "domain", "website_legal_page" ] }, { "type": "null" } ] }, "evidence": { "type": "object", "additionalProperties": true, "description": "matched_on website_legal_page: the page and snippet the match rests on." } }, "required": [ "company_number", "company_name", "match_confidence", "matched_on" ], "additionalProperties": true }, "Row": { "type": "object", "properties": { "ref": { "type": "string", "description": "This is your reference, which is echoed back." }, "status": { "$ref": "#/components/schemas/RowStatus" }, "blocks": { "$ref": "#/components/schemas/RowBlocks" }, "matched": { "anyOf": [ { "$ref": "#/components/schemas/Matched" }, { "type": "null" } ] }, "pending_blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" }, "description": "Blocks still being worked on (progressive resolve)." } }, "required": [ "ref", "status", "blocks", "matched" ], "additionalProperties": true, "examples": [ { "ref": "", "status": "done", "blocks": { "company_identity": { "status": "available", "value": { "incorporated_on": "1993-04-01", "company_category": "Private Limited Company", "country_of_origin": "United Kingdom", "legal_form": "Limited", "company_status": "Active", "status_group": "active", "trading_name": "Hotel Chocolat", "trading_name_source": "third_party_profile" }, "source": "companies_house" }, "registered_address": { "status": "available", "value": { "address_line_1": "MINT HOUSE", "address_line_2": "NEWARK CLOSE", "locality": "ROYSTON", "region": "HERTFORDSHIRE", "postal_code": "SG8 5HL" }, "source": "companies_house" }, "filing_status": { "status": "available", "value": { "accounts_last_made_up_on": "2024-12-28", "accounts_next_due_on": "2026-09-28", "accounts_category": "AUDIT EXEMPTION SUBSIDIARY", "confirmation_statement_last_made_up_on": "2026-03-31", "confirmation_statement_next_due_on": "2027-04-14" }, "source": "companies_house", "detail": { "freshness": { "checked_live": false } }, "as_of": "2026-07-01" }, "officers": { "status": "available", "value": { "total": 21, "active": 4, "current": [ { "name": "NICOLA LACEY", "role": "Director", "appointed_on": "2024-08-23", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "DIRECTOR", "person_number": "184966970001", "person_key": "18496697", "date_of_birth": { "month": 10, "year": 1972 } }, { "name": "DANIEL MARK JENKS", "role": "Director", "appointed_on": "2026-02-28", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": null, "person_number": "346063570001", "person_key": "34606357", "date_of_birth": { "month": 7, "year": 1983 } }, { "name": "Isabel Louise STATON", "role": "Director", "appointed_on": "2026-04-20", "nationality": "British", "country_of_residence": "United Kingdom", "occupation": null, "person_number": "XlZ47f6Fh_bvCYU-tcCitVk7d6w", "date_of_birth": { "month": 12, "year": 1978 } }, { "name": "INDIGO CORPORATE SECRETARY LIMITED", "role": "Secretary", "appointed_on": "2021-06-30", "nationality": null, "country_of_residence": null, "occupation": null, "person_number": "281695990002", "person_key": "28169599", "is_corporate": true } ], "resigned": 17, "former": [ { "name": "GREGOIRE ALEXANDRE GAILLOT", "role": "Director", "appointed_on": "2024-01-25", "nationality": "FRENCH", "country_of_residence": "UNITED STATES", "occupation": "FINANCE DIRECTOR", "person_number": "318583360001", "person_key": "31858336", "date_of_birth": { "month": 12, "year": 1980 }, "resigned_on": "2026-04-20" }, { "name": "LYSA MARIA HARDY", "role": "Director", "appointed_on": "2024-08-23", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "DIRECTOR", "person_number": "165408450002", "person_key": "16540845", "date_of_birth": { "month": 4, "year": 1970 }, "resigned_on": "2025-08-27" }, { "name": "PAULA KELLY", "role": "Director", "appointed_on": "2024-01-25", "nationality": "AMERICAN", "country_of_residence": "UNITED STATES", "occupation": "LAWYER", "person_number": "318580620001", "person_key": "31858062", "date_of_birth": { "month": 7, "year": 1967 }, "resigned_on": "2024-08-23" }, { "name": "ANGUS THIRLWELL", "role": "Director", "appointed_on": "1993-04-01", "nationality": "BRITISH", "country_of_residence": "ENGLAND", "occupation": "DIRECTOR", "person_number": "033391700002", "person_key": "03339170", "date_of_birth": { "month": 4, "year": 1963 }, "resigned_on": "2024-08-23" }, { "name": "JONATHAN FIRTH AKEHURST", "role": "Director", "appointed_on": "2023-05-15", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "COMPANY DIRECTOR", "person_number": "309030640001", "person_key": "30903064", "date_of_birth": { "month": 1, "year": 1983 }, "resigned_on": "2024-01-25" }, { "name": "LYSA MARIA HARDY", "role": "Director", "appointed_on": "2020-09-18", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "CHIEF MARKETING OFFICER", "person_number": "165408450002", "person_key": "16540845", "date_of_birth": { "month": 4, "year": 1970 }, "resigned_on": "2024-01-25" }, { "name": "MATTHEW PAUL MARGERESON", "role": "Director", "appointed_on": "2007-02-07", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "COMPANY DIRECTOR", "person_number": "118935720001", "person_key": "11893572", "date_of_birth": { "month": 12, "year": 1970 }, "resigned_on": "2024-01-25" }, { "name": "PETER MARK HARRIS", "role": "Director", "appointed_on": "1993-04-01", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "DIRECTOR", "person_number": "033391720002", "person_key": "03339172", "date_of_birth": { "month": 2, "year": 1955 }, "resigned_on": "2024-01-25" }, { "name": "MATTHEW ROBERT PHILLIP PRITCHARD", "role": "Director", "appointed_on": "2014-11-20", "nationality": "BRITISH", "country_of_residence": "ENGLAND", "occupation": "COMPANY DIRECTOR", "person_number": "192967640001", "person_key": "19296764", "date_of_birth": { "month": 5, "year": 1974 }, "resigned_on": "2023-01-31" }, { "name": "PETER MARK HARRIS", "role": "Secretary", "appointed_on": "1993-04-01", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "DIRECTOR", "person_number": "033391720002", "person_key": "03339172", "date_of_birth": { "month": 2, "year": 1955 }, "resigned_on": "2021-06-30" }, { "name": "HEATHER FRANCES BLACKMAN", "role": "Director", "appointed_on": "2008-11-18", "nationality": "BRITISH", "country_of_residence": "ENGLAND", "occupation": "COMPANY DIRECTOR", "person_number": "206665810001", "person_key": "20666581", "date_of_birth": { "month": 2, "year": 1963 }, "resigned_on": "2015-05-31" }, { "name": "MICHAEL CHRISTOPHER DOYLE", "role": "Director", "appointed_on": "2011-09-05", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "COMPANY DIRECTOR", "person_number": "138725480001", "person_key": "13872548", "date_of_birth": { "month": 6, "year": 1972 }, "resigned_on": "2013-12-31" }, { "name": "EMIL FREDRIK CHRISTER AHLIN", "role": "Director", "appointed_on": "2008-11-17", "nationality": "SWEDISH", "country_of_residence": "ENGLAND", "occupation": "COMPANY DIRECTOR", "person_number": "134700840002", "person_key": "13470084", "date_of_birth": { "month": 10, "year": 1970 }, "resigned_on": "2012-04-13" }, { "name": "PETER ARTHUR KLAUBER", "role": "Director", "appointed_on": "2008-09-01", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "COMPANY DIRECTOR", "person_number": "133070060001", "person_key": "13307006", "date_of_birth": { "month": 4, "year": 1955 }, "resigned_on": "2011-06-30" }, { "name": "LYNN CUNNINGHAM", "role": "Director", "appointed_on": "2005-01-10", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "COMPANY DIRECTOR", "person_number": "102522780003", "person_key": "10252278", "date_of_birth": { "month": 1, "year": 1968 }, "resigned_on": "2011-05-20" }, { "name": "JOHN CYRIL HADLEY", "role": "Director", "appointed_on": "2004-05-17", "nationality": "BRITISH", "country_of_residence": "UNITED KINGDOM", "occupation": "COMPANY DIRECTOR", "person_number": "163797310001", "person_key": "16379731", "date_of_birth": { "month": 3, "year": 1946 }, "resigned_on": "2009-01-28" }, { "name": "SWIFT INCORPORATIONS LIMITED", "role": "Secretary", "appointed_on": "1993-04-01", "nationality": "BRITISH", "country_of_residence": null, "occupation": null, "person_number": "900008300001", "person_key": "90000830", "is_corporate": true, "resigned_on": "1993-04-01" } ], "ages": { "average": 57.9, "youngest": 43, "oldest": 80 } }, "source": "companies_house", "as_of": "2026-06-01", "detail": { "freshness": { "checked_live": false } } }, "controllers": { "status": "available", "value": { "controllers": [ { "type": "company", "name": "Hotel Chocolat Group Ltd", "country_registered": "England And Wales", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "notified_on": "2016-04-06", "company_number": "08612206" } ], "has_corporate_owner": true, "control": { "has_corporate_controller": true, "has_individual_controller": false, "no_controller_on_register": false, "statement": null }, "ceased_controllers": [] }, "source": "companies_house_psc", "detail": { "freshness": { "checked_live": false } }, "as_of": "2026-07-01" }, "corporate_owners": { "status": "available", "value": { "has_corporate_owner": true, "owners": [ { "name": "Hotel Chocolat Group Ltd", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "notified_on": "2016-04-06", "country_registered": "England And Wales", "company_number": "08612206", "nature_of_business": { "status": "not_found", "reason": "no_description_on_file" } } ] }, "source": "companies_house_psc" }, "ultimate_owner": { "status": "available", "value": { "company_name": "HOTEL CHOCOLAT GROUP LIMITED", "company_number": "08612206", "depth": 1, "resolved_by": "self", "chain": [ { "company_name": "HOTEL CHOCOLAT GROUP LIMITED", "company_number": "08612206" } ] }, "source": "companies_house_psc" }, "charges": { "status": "available", "value": { "outstanding_count": 0, "satisfied_count": 17, "total_count": 17, "holders": [], "charges": [], "satisfied_charges": [ { "charge_code": "028057300017", "status": "satisfied", "created_on": "2021-07-16", "registered_on": "2021-07-21", "persons_entitled": [ "LLOYDS BANK PLC AS SECURITY TRUSTEE FOR THE SECURED PARTIES" ], "particulars": "N/A CONTAINS FIXED CHARGE. CONTAINS FLOATING CHARGE. FLOATING CHARGE COVERS ALL THE PROPERTY OR UNDERTAKING OF THE COMPANY. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "floating_charge", "floating_charge_covers_all", "negative_pledge" ], "satisfied_on": "2024-02-23" }, { "charge_code": "028057300016", "status": "satisfied", "created_on": "2021-04-13", "registered_on": "2021-04-19", "persons_entitled": [ "LLOYDS BANK CORPORATE MARKETS PLC" ], "particulars": "NOT APPLICABLE. CONTAINS FIXED CHARGE. CONTAINS FLOATING CHARGE. FLOATING CHARGE COVERS ALL THE PROPERTY OR UNDERTAKING OF THE COMPANY. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "floating_charge", "floating_charge_covers_all", "negative_pledge" ], "satisfied_on": "2021-07-28" }, { "charge_code": "028057300015", "status": "satisfied", "created_on": "2020-05-04", "registered_on": "2020-05-07", "persons_entitled": [ "LLOYDS BANK PLC" ], "particulars": "NOT APPLICABLE. CONTAINS FIXED CHARGE. CONTAINS FLOATING CHARGE. FLOATING CHARGE COVERS ALL THE PROPERTY OR UNDERTAKING OF THE COMPANY. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "floating_charge", "floating_charge_covers_all", "negative_pledge" ], "satisfied_on": "2021-07-26" }, { "charge_code": "028057300014", "status": "satisfied", "created_on": "2015-07-02", "registered_on": "2015-07-09", "persons_entitled": [ "LLOYDS BANK PLC" ], "particulars": "CONTAINS FIXED CHARGE. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "negative_pledge" ], "satisfied_on": "2021-07-26" }, { "charge_code": "028057300013", "status": "satisfied", "created_on": "2014-11-05", "registered_on": "2014-11-11", "persons_entitled": [ "LLOYDS BANK PLC" ], "particulars": "CONTAINS FIXED CHARGE. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "negative_pledge" ], "satisfied_on": "2021-07-26" }, { "charge_code": "028057300012", "status": "satisfied", "created_on": "2014-10-13", "registered_on": "2014-10-21", "persons_entitled": [ "LLOYDS BANK PLC" ], "particulars": "CONTAINS FIXED CHARGE. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "negative_pledge" ], "satisfied_on": "2021-07-26" }, { "charge_code": "028057300010", "status": "satisfied", "created_on": "2014-04-02", "registered_on": "2014-04-04", "persons_entitled": [ "LLOYDS BANK PLC" ], "particulars": "CONTAINS FIXED CHARGE. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "negative_pledge" ], "satisfied_on": "2021-07-26" }, { "charge_code": "028057300007", "status": "satisfied", "created_on": "2010-01-26", "registered_on": "2010-01-27", "persons_entitled": [ "LLOYDS TSB BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY AND/OR ALL OR ANY OF THE COMPANIES NAMED THEREIN TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "A DEED OF ADMISSION TO AN OMNIBUS GUARANTEE AND SET-OFF AGREEMENT", "particulars": "ANY SUM OR SUMS FOR THE TIME BEING STANDING TO THE CREDIT OF ANY PRESENT OR FUTURE ACCOUNT OF THE COMPANY WITH THE BANK", "satisfied_on": "2021-07-26" }, { "charge_code": "028057300006", "status": "satisfied", "created_on": "2009-10-06", "registered_on": "2009-10-08", "persons_entitled": [ "LLOYDS TSB BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY AND/OR ALL OR ANY OF THE COMPANIES NAMED THEREIN TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "DEED OF ADMISSION TO AN OMNIBUS GUARANTEE AND SET-OFF AGREEMENT DATED 8TH AUGUST 2006 AND", "particulars": "ANY SUM OR SUMS FOR THE TIME BEING STANDING TO THE CREDIT OF ANY ONE OR MORE OF ANY PRESENT OR FUTURE ACCOUNTS OF THE COMPANIES OR ANY OF THEM WITH THE BANK", "satisfied_on": "2021-07-26" }, { "charge_code": "028057300004", "status": "satisfied", "created_on": "2006-08-08", "registered_on": "2006-08-21", "persons_entitled": [ "LLOYDS TSB BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY AND/OR ALL OR ANY OF THE OTHER COMPANIES NAMED THEREIN TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "AN OMNIBUS GUARANTEE AND SET-OFF AGREEMENT", "particulars": "ANY SUM OR SUMS FROM TIME TO TIME BEING STANDING TO THE CREDIT OF ANY ONE OR MORE OF ANY PRESENT OR FUTURE ACCOUNTS OF THE COMPANIES OR ANY OF THEM WITH THE BANK (INCLUDING ANY ACCOUNTS HELD IN THE BANK'S NAME WITH ANY DESIGNATION WHICH INCLUDES THE NAME (S) OF THE COMPANIES OR ANY OF THEM) WHETHER SUCH ACCOUNTS BE DENOMINATED IN STERLING OR IN A CURRENCY OR CURRENCIES OTHER THAN STERLING", "satisfied_on": "2021-07-26" }, { "charge_code": "028057300002", "status": "satisfied", "created_on": "1996-07-01", "registered_on": "1996-07-05", "persons_entitled": [ "TSB BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "MORTGAGE DEBENTURE", "particulars": ". FIXED AND FLOATING CHARGES OVER THE UNDERTAKING AND ALL PROPERTY AND ASSETS PRESENT AND FUTURE INCLUDING GOODWILL BOOKDEBTS UNCALLED CAPITAL BUILDINGS FIXTURES FIXED PLANT AND MACHINERY SEE THE MORTGAGE CHARGE DOCUMENT FOR FULL DETAILS", "satisfied_on": "2021-07-26" }, { "charge_code": "028057300009", "status": "satisfied", "created_on": "2013-07-17", "registered_on": "2013-07-31", "persons_entitled": [ "LOMBARD NORTH CENTRAL PLC" ], "particulars": "CONTAINS FIXED CHARGE. NOTIFICATION OF ADDITION TO OR AMENDMENT OF CHARGE.", "contains": [ "fixed_charge" ], "satisfied_on": "2020-05-01" }, { "charge_code": "028057300008", "status": "satisfied", "created_on": "2012-11-27", "registered_on": "2012-11-30", "persons_entitled": [ "LOMBARD NORTH CENTRAL PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "CHATTEL MORTGAGE", "particulars": "USED 2009 KNOBEL KCM 9/18 OMEGA SERIAL NO. 07-KCM-39, USED 2009 KNOBEL VIBRATION TABLE VT/H, USED 2009 KNOBEL 16/32 ONE SHOT CENTRE FILLING SERIAL NO 09-KCM-21 AND USED 2009 KNOBEL 16/32 CAD - ALPHA SERIAL NO HD09-KCM-22", "satisfied_on": "2020-05-01" }, { "charge_code": "028057300005", "status": "satisfied", "created_on": "2007-09-05", "registered_on": "2007-09-19", "persons_entitled": [ "LLOYDS TSB BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "MORTGAGE", "particulars": "F/H PROPERTY K/A OR BEING 1 GLEBE ROAD OFF ST PETERS ROAD HUNTINGDON T/NO CB2001 TOGETHER WITH ALL BUILDINGS AND FIXTURES (INCLUDING TRADE FIXTURES) FIXED PLANT AND MACHINERY BY WAY OF FIXED CHARGE ALL PRESENT AND FUTURE BOOK AND OTHER DEBTS FLOATING CHARGE OVER ALL MOVEABLE PLANT MACHINERY IMPLEMENTS UTENSILS FURNITURE AND EQUIPMENT BY WAY OF ASSIGNMENT THE GOODWILL OF THE BUSINESS (IF ANY) THE FULL BENEFIT OF ALL LICENCES AND ALL GUARANTEES", "satisfied_on": "2017-05-30" }, { "charge_code": "028057300003", "status": "satisfied", "created_on": "2004-07-30", "registered_on": "2004-08-04", "persons_entitled": [ "LLOYDS TSB BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "MORTGAGE", "particulars": "F/H PROPERTY K/A 3 REDWONGS WAY, HUNTINGDON T/NO. HN920 TOGETHER WITH ALL BUILDINGS AND FIXTURES (INCLUDING TRADE FIXTURES) FIXED PLANT AND MACHINERY BY WAY OF FIXED CHARGE ALL PRESENT AND FUTURE BOOK AND OTHER DEBTS FLOATING CHARGE OVER ALL MOVEABLE PLANT MACHINERY IMPLEMENTS UTENSILS FURNITURE AND EQUIPMENT BY WAY OF ASSIGNMENT THE GOODWILL OF THE BUSINESS (IF ANY) THE FULL BENEFIT OF ALL LICENCES AND ALL GUARANTEES", "satisfied_on": "2017-05-30" }, { "charge_code": "028057300011", "status": "satisfied", "created_on": "2014-10-13", "registered_on": "2014-10-21", "persons_entitled": [ "LLOYDS BANK PLC" ], "particulars": "L/H UNIT SU31, SOUTHGATE, BATH T/NO ST307022 CONTAINS FIXED CHARGE. CONTAINS FLOATING CHARGE. CONTAINS NEGATIVE PLEDGE.", "contains": [ "fixed_charge", "floating_charge", "negative_pledge" ], "satisfied_on": "2017-02-01" }, { "charge_code": "028057300001", "status": "satisfied", "created_on": "1994-09-13", "registered_on": "1994-09-16", "persons_entitled": [ "BARCLAYS BANK PLC" ], "amount_secured": "ALL MONIES DUE OR TO BECOME DUE FROM THE COMPANY TO THE CHARGEE ON ANY ACCOUNT WHATSOEVER", "type": "DEBENTURE", "particulars": "FIXED AND FLOATING CHARGES OVER THE UNDERTAKING AND ALL PROPERTY AND ASSETS PRESENT AND FUTURE INCLUDING GOODWILL BOOKDEBTS UNCALLED CAPITAL BUILDINGS FIXTURES FIXED PLANT AND MACHINERY SEE THE MORTGAGE CHARGE DOCUMENT FOR FULL DETAILS", "satisfied_on": "1996-09-19" } ], "past_holders": [ "LLOYDS BANK PLC AS SECURITY TRUSTEE FOR THE SECURED PARTIES", "LLOYDS BANK CORPORATE MARKETS PLC", "LLOYDS BANK PLC", "LLOYDS TSB BANK PLC", "TSB BANK PLC", "LOMBARD NORTH CENTRAL PLC", "BARCLAYS BANK PLC" ], "latest_created_on": "2021-07-16", "latest_satisfied_on": "2024-02-23" }, "source": "companies_house", "as_of": "2021-07-21", "detail": { "freshness": { "checked_live": false } } }, "industry": { "status": "available", "value": { "sic": [ { "code": "10821", "description": "Manufacture of cocoa and chocolate confectionery", "scheme": "sic_2007", "is_primary": true } ], "label": "food and beverage manufacturing", "label_source": "sic", "nace": [ { "code": "10.82", "from_sic": "10821" } ], "sic_is_generic": false }, "source": "companies_house", "derived": true } }, "matched": { "company_number": "02805730", "company_name": "HOTEL CHOCOLAT LIMITED", "match_confidence": 1, "matched_on": "company_number" } } ] }, "Warning": { "type": "object", "description": "Some requested blocks are not enabled for the key; they come back not_enabled and every other block is unaffected.", "properties": { "code": { "type": "string", "const": "blocks_not_enabled" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" } }, "detail": { "type": "string" } }, "required": [ "code", "blocks", "detail" ], "additionalProperties": true }, "ResolveResponse": { "description": "The row for one company, with its job id. With defer_live=true also complete, pending_blocks, results_url, status_url and, while pending, retry_after_ms.", "allOf": [ { "$ref": "#/components/schemas/Row" }, { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "When the row stops being available; null while the row is unfinished, or with store=false." }, { "type": "null" } ] }, "stored": { "type": "boolean", "const": false, "description": "store=false: the row is not kept after answering." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "complete": { "type": "boolean", "description": "defer_live: every block has answered." }, "results_url": { "type": "string", "format": "uri" }, "status_url": { "type": "string", "format": "uri" }, "retry_after_ms": { "type": "integer", "description": "defer_live and not complete: wait this long before polling results_url." } }, "required": [ "job_id", "expires_at" ], "additionalProperties": true } ] }, "JobCounts": { "type": "object", "properties": { "total": { "type": "integer" }, "processed": { "type": "integer" }, "succeeded": { "type": "integer" }, "not_found": { "type": "integer" }, "failed": { "type": "integer" }, "site_unreachable": { "type": "integer", "description": "Rows whose website would not open (not a subset of the other counts)." } }, "required": [ "total", "processed", "succeeded", "not_found", "failed", "site_unreachable" ], "additionalProperties": true }, "Job": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/JobStatus" }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" } }, "counts": { "$ref": "#/components/schemas/JobCounts" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "pull", "webhook" ] } }, "required": [ "mode" ], "additionalProperties": true }, "results_ready": { "type": "boolean", "description": "The job is terminal: every row is final." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time", "description": "When the job's rows stop being available. It is `null` while the job is running." }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" } }, "retry_after_ms": { "type": "integer", "description": "For a job that is not terminal, this is the polling delay in milliseconds." }, "results_url": { "type": "string", "format": "uri", "description": "This is present only on a job created by GET /v1/resolve?wait=false." } }, "required": [ "job_id", "status", "blocks", "counts", "delivery", "results_ready", "expires_at", "created_at", "finished_at" ], "additionalProperties": true }, "RowInput": { "type": "object", "description": "Exactly one of company_number, company_name or domain.", "properties": { "ref": { "type": "string", "description": "This is your reference, which is echoed back.", "maxLength": 120 }, "company_number": { "type": "string", "description": "Companies House number.", "maxLength": 20 }, "company_name": { "type": "string", "description": "Registered name. A name that is plainly a website (no spaces, a dot) is treated as domain.", "maxLength": 500 }, "domain": { "type": "string", "description": "A bare host or a URL. Cannot be combined with number or name.", "maxLength": 255 } }, "additionalProperties": false }, "JobOptions": { "type": "object", "description": "Unknown option names are ignored.", "properties": { "validation": { "type": "array", "items": { "type": "string", "enum": [ "none", "rules", "live", "officers", "ai" ] }, "description": "domain_validation modes. Default rules and live." }, "min_confidence": { "type": "number", "description": "Your threshold for domain_validation and the website-derived blocks. Default 0.5.", "minimum": 0, "maximum": 1 }, "discover": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" }, "description": "Blocks to look up when the company has no value on file. Jobs default to [\"domain\"]; pass [] to skip the lookup." }, "force_refresh": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" }, "description": "Blocks to look up again although a value is on file." }, "max_live_lookups": { "type": "integer", "description": "How many rows may run a website search; rows past it answer `source_busy`. 0 means no searches.", "minimum": 0 }, "web_search": { "type": "boolean", "description": "This is a Premium option enabled per account. Refused with 403 when not enabled." }, "read_accounts_pdf": { "type": "boolean", "description": "financials_live: read accounts filed only as PDF. Off by default." }, "google_business": { "type": "boolean", "description": "For trading_address, this adds the listing check. Off by default." }, "ai_apply_multiplier": { "type": "boolean", "description": "ai validation mode: apply the AI factor to the score (off by default)." }, "contact_roles": { "type": "array", "items": { "type": "string", "enum": [ "owner", "director", "finance", "operations" ] } }, "max_contacts": { "type": "integer", "description": "Default 3.", "minimum": 1, "maximum": 5 }, "verify_emails": { "type": "boolean" }, "contacts_lookup": { "type": "string", "enum": [ "cached_only", "live" ] }, "include_phone": { "type": "boolean" }, "include_linkedin": { "type": "boolean" }, "delivery": { "type": "string", "enum": [ "pull", "webhook" ], "description": "pull (default): collect results from the results endpoint. webhook is accepted; no callback is sent." }, "callback_url": { "type": "string", "format": "uri", "description": "Accepted with delivery webhook; not called." } }, "additionalProperties": true }, "JobCreateRequest": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/RowInput" }, "minItems": 1, "maxItems": 250000 }, "blocks": { "type": "array", "items": { "$ref": "#/components/schemas/BlockKey" }, "minItems": 1 }, "options": { "$ref": "#/components/schemas/JobOptions" } }, "required": [ "rows", "blocks" ], "additionalProperties": true }, "ResultsPage": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Row" }, "description": "Every row in seq order, whatever its status." }, "next_cursor": { "anyOf": [ { "type": "string", "description": "Pass as cursor for the next page; null at the end." }, { "type": "null" } ] }, "remaining": { "type": "integer", "description": "Rows after this page." }, "results_ready": { "type": "boolean" }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "retry_after_ms": { "type": "integer", "description": "While the job is not terminal." } }, "required": [ "results", "next_cursor", "remaining", "results_ready", "expires_at" ], "additionalProperties": true }, "QuarantinedRow": { "type": "object", "properties": { "ref": { "type": "string" }, "key": { "type": "object", "properties": { "company_number": { "type": "string" }, "company_name": { "type": "string" }, "domain": { "type": "string" } }, "required": [ "company_number", "company_name", "domain" ], "additionalProperties": true }, "reason": { "$ref": "#/components/schemas/RowFailureReason" }, "retryable": { "type": "boolean" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "host_type": { "type": "string", "enum": [ "register", "directory", "social", "site_builder" ] }, "site_lookup": { "$ref": "#/components/schemas/SiteLookup" } }, "required": [ "ref", "key", "reason", "retryable" ], "additionalProperties": true }, "ErrorsPage": { "type": "object", "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/QuarantinedRow" } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryable_count": { "type": "integer", "description": "Failed rows worth resubmitting." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "errors", "next_cursor", "retryable_count", "expires_at" ], "additionalProperties": true }, "UsageOutcomes": { "type": "object", "description": "Events by outcome. Only delivered is charged.", "properties": { "delivered": { "type": "integer" }, "not_found": { "type": "integer" }, "ambiguous_match": { "type": "integer" }, "not_enabled": { "type": "integer" }, "error": { "type": "integer" }, "cancelled": { "type": "integer" } }, "additionalProperties": { "type": "integer" } }, "Usage": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" } }, "required": [ "from", "to" ], "additionalProperties": true }, "granularity": { "type": "string", "enum": [ "block", "day" ] }, "pricing_status": { "type": "string", "enum": [ "not_priced", "agreed" ], "description": "not_priced: counts only. agreed: contract prices are loaded, and amount and currency appear." }, "pricing_note": { "type": "string", "description": "With not_priced." }, "blocks": { "type": "array", "description": "granularity block.", "items": { "type": "object", "properties": { "block": { "$ref": "#/components/schemas/BlockKey" }, "events": { "type": "integer" }, "billed_events": { "type": "integer" }, "outcomes": { "$ref": "#/components/schemas/UsageOutcomes" }, "currency": { "type": "string", "description": "Only when priced." }, "price_is_provisional": { "type": "boolean", "const": false }, "amount": { "type": "string", "description": "Only when priced: a decimal string." } }, "required": [ "block", "events", "billed_events", "outcomes" ], "additionalProperties": true } }, "days": { "type": "array", "description": "granularity day: every UTC day in the range, a quiet day at zero.", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "events": { "type": "integer" }, "billed_events": { "type": "integer" }, "outcomes": { "$ref": "#/components/schemas/UsageOutcomes" }, "blocks": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Billed events by block." } }, "required": [ "date", "events", "billed_events", "outcomes", "blocks" ], "additionalProperties": true } }, "totals": { "type": "object", "properties": { "events": { "type": "integer" }, "billed_events": { "type": "integer" }, "rows": { "type": "integer", "description": "granularity block: rows accounted for (a cancel counts the skipped remainder)." }, "billed_rows": { "type": "integer" }, "invoiceable": { "type": "boolean", "description": "granularity block: prices are agreed." }, "currencies": { "type": "array", "items": { "type": "string" }, "description": "Only when priced." }, "price_is_provisional": { "type": "boolean", "const": false }, "amount": { "type": "string", "description": "Only when priced." } }, "required": [ "events", "billed_events" ], "additionalProperties": true }, "billing_rule": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" } }, "required": [ "range", "granularity", "pricing_status", "totals", "billing_rule" ], "additionalProperties": true } }, "examples": { "jobs_404": { "summary": "GET /v1/enrich/jobs/00000000-0000-0000-0000-000000000000 (404)", "value": { "detail": "Not found." } }, "jobs_cancel_200": { "summary": "POST /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875/cancel (200)", "description": "Cancelling a job that already finished returns it unchanged; a retried cancel is safe.", "value": { "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875", "status": "completed", "blocks": [ "domain", "domain_validation" ], "counts": { "total": 3, "processed": 3, "succeeded": 3, "not_found": 0, "failed": 0, "site_unreachable": 0 }, "delivery": { "mode": "pull" }, "results_ready": true, "expires_at": "2026-10-15T07:09:32.659195Z", "created_at": "2026-09-15T07:07:47.705727Z", "finished_at": "2026-09-15T07:09:32.659195Z" } }, "jobs_create_202": { "summary": "POST /v1/enrich/jobs (202)", "value": { "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875", "status": "queued", "blocks": [ "domain", "domain_validation" ], "counts": { "total": 3, "processed": 0, "succeeded": 0, "not_found": 0, "failed": 0, "site_unreachable": 0 }, "delivery": { "mode": "pull" }, "results_ready": false, "expires_at": null, "created_at": "2026-09-15T07:07:47.705727Z", "finished_at": null } }, "jobs_create_409_idempotency": { "summary": "POST /v1/enrich/jobs (409)", "description": "The same X-Idempotency-Key with a different body.", "value": { "detail": "This idempotency key was already used for a different request. Use a new key, or resend the original body." } }, "jobs_create_replay_200": { "summary": "POST /v1/enrich/jobs (200)", "description": "The same body with the same X-Idempotency-Key: the original job, 200 instead of 202.", "value": { "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875", "status": "queued", "blocks": [ "domain", "domain_validation" ], "counts": { "total": 3, "processed": 0, "succeeded": 0, "not_found": 0, "failed": 0, "site_unreachable": 0 }, "delivery": { "mode": "pull" }, "results_ready": false, "expires_at": null, "created_at": "2026-09-15T07:07:47.705727Z", "finished_at": null } }, "jobs_errors_200": { "summary": "GET /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875/errors (200)", "value": { "errors": [], "next_cursor": null, "retryable_count": 0, "expires_at": "2026-10-15T07:09:32.659195Z" } }, "jobs_results_400_cursor": { "summary": "GET /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875/results (400)", "value": { "detail": "Malformed cursor. Use the next_cursor from the previous page, or omit it to start." } }, "jobs_results_page1_200": { "summary": "GET /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875/results (200)", "description": "With limit=2, the page holds two rows and a next_cursor.", "value": { "results": [ { "ref": "crm-1001", "status": "done", "blocks": { "domain": { "status": "available", "value": "hotelchocolat.com", "source": "cache", "final_url": "https://www.hotelchocolat.com/uk" }, "domain_validation": { "status": "available", "value": { "domain": "hotelchocolat.com", "dns_resolves": true, "email_deliverable": true, "site_live": true, "http_status": 200, "final_url": "https://www.hotelchocolat.com/uk", "director_check": "companies_house", "score": 100, "outcome": "accept", "checks": { "legal_name_exact": 0.5, "business_name": true, "same_postcode": true, "similar_postcode": true, "city_match": true, "county_match": true, "address_match": true, "director_match": false, "company_number": true, "other_company_number": false, "foreign_registration": false, "uk_domain": false, "phone_present": true, "generic_platform": false, "parked": false }, "contributions": { "legal_name_exact": 15, "business_name": 15, "same_postcode": 25, "similar_postcode": 8, "city_match": 10, "county_match": 5, "address_match": 15, "phone_present": 3, "company_number": 50 }, "reasons": [ "all checks passed" ] }, "source": "zorro_validator", "confidence": 1, "flagged_for_review": false, "detail": { "evidence": { "hard_matches": { "company_number": { "url": "https://www.hotelchocolat.com/uk/i/terms-and-conditions.html", "snippet": "…ngdom. Registered in England and Wales under company number 2805730. VAT number 945695766 (“Hotel Chocolat”) 2. Information Abo…" }, "postcode": { "url": "https://www.hotelchocolat.com/uk", "snippet": "…pp © Hotel Chocolat 2026. Mint House, Newark Close, Royston SG8 5HL, UK An Affiliate of Mars, Incorporated Terms & Conditions S…" }, "registered_address": { "url": "https://www.hotelchocolat.com/uk", "snippet": "…s Sign Up Follow Us Download Our App © Hotel Chocolat 2026. Mint House, Newark Close, Royston SG8 5HL, UK An Affiliate of Mars, In…" } }, "name_match": { "kind": "trading_name", "url": "https://www.hotelchocolat.com/uk", "snippet": "Luxury Chocolates | Chocolate Gifts & Hampers | Hotel Chocolat Skip to Content Help Help & Support FREE Standard Delivery…" } } } } }, "matched": { "company_number": "02805730", "company_name": "HOTEL CHOCOLAT LIMITED", "match_confidence": 1, "matched_on": "company_number" } }, { "ref": "crm-1002", "status": "done", "blocks": { "domain": { "status": "available", "value": "gymshark.com", "source": "cache", "final_url": "https://www.gymshark.com/" }, "domain_validation": { "status": "available", "value": { "domain": "gymshark.com", "dns_resolves": true, "email_deliverable": true, "site_live": true, "http_status": 200, "final_url": "https://www.gymshark.com/", "director_check": "companies_house", "score": 95, "outcome": "accept", "checks": { "legal_name_exact": true, "business_name": true, "same_postcode": false, "similar_postcode": false, "city_match": true, "county_match": false, "address_match": true, "director_match": true, "company_number": false, "other_company_number": false, "foreign_registration": false, "uk_domain": false, "phone_present": false, "generic_platform": false, "parked": false }, "contributions": { "legal_name_exact": 30, "business_name": 15, "city_match": 10, "address_match": 15, "director_match": 25 }, "reasons": [ "all checks passed" ] }, "source": "zorro_validator", "confidence": 0.95, "flagged_for_review": false, "detail": { "evidence": { "hard_matches": { "director": { "url": "https://www.gymshark.com/pages/about-us", "snippet": "…e do today to prepare for tomorrow. Gymshark is led by: Ben Francis - Founder & Chief Executive Officer Noel Mack - Chief Brand…", "surname": "francis" } }, "name_match": { "kind": "legal_name", "url": "https://www.gymshark.com/pages/terms-and-conditions", "snippet": "…Language Selector dropdown English English Español © 2026 | Gymshark Limited | All Rights Reserved. | We Do Gym." } } } } }, "matched": { "company_number": "08130873", "company_name": "GYMSHARK LTD", "match_confidence": 1, "matched_on": "company_number" } } ], "next_cursor": "eyJzZXEiOjJ9", "remaining": 1, "results_ready": true, "expires_at": "2026-10-15T07:09:32.659195Z" } }, "jobs_results_page2_200": { "summary": "GET /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875/results (200)", "description": "This page was fetched with cursor set to the previous next_cursor; on the last page, next_cursor is null.", "value": { "results": [ { "ref": "crm-1003", "status": "done", "blocks": { "domain": { "status": "available", "value": "allica.bank", "source": "cache", "flagged_for_review": false, "verification_profile": "verifiable", "reason": "provenance_uncertain_but_validated", "final_url": "https://www.allica.bank/" }, "domain_validation": { "status": "available", "value": { "domain": "allica.bank", "dns_resolves": true, "email_deliverable": true, "site_live": true, "http_status": 200, "final_url": "https://www.allica.bank/", "director_check": "companies_house", "score": 100, "outcome": "accept", "checks": { "legal_name_exact": true, "business_name": true, "same_postcode": true, "similar_postcode": true, "city_match": true, "county_match": false, "address_match": true, "director_match": false, "company_number": true, "other_company_number": false, "foreign_registration": false, "uk_domain": false, "phone_present": true, "generic_platform": false, "parked": false }, "contributions": { "legal_name_exact": 30, "business_name": 15, "same_postcode": 25, "similar_postcode": 8, "city_match": 10, "address_match": 15, "phone_present": 3, "company_number": 50 }, "reasons": [ "all checks passed" ] }, "source": "zorro_validator", "confidence": 1, "flagged_for_review": false, "detail": { "evidence": { "hard_matches": { "company_number": { "url": "https://www.allica.bank/", "snippet": "…2A 2DT. Registered in England and Wales with company number 07706156. Allica Bank savings accounts and business current account…" }, "postcode": { "url": "https://www.allica.bank/", "snippet": "…Registered office: 4th/5th Floor, 15 Worship Street, London EC2A 2DT. Registered in England and Wales with company number 077061…" }, "registered_address": { "url": "https://www.allica.bank/", "snippet": "…tial Regulation Authority (FRN: 821851). Registered office: 4th/5th Floor, 15 Worship Street, London EC2A 2DT. Registered in England and Wales with comp…" } }, "name_match": { "kind": "legal_name", "url": "https://www.allica.bank/", "snippet": "…ints Tariff of fees Fraud advice Trustpilot Connect with us Allica Bank Limited is authorised by the Prudential Regulation Authority and re…" } } } } }, "matched": { "company_number": "07706156", "company_name": "ALLICA BANK LIMITED", "match_confidence": 1, "matched_on": "company_number" } } ], "next_cursor": null, "remaining": 0, "results_ready": true, "expires_at": "2026-10-15T07:09:32.659195Z" } }, "jobs_status_completed_200": { "summary": "GET /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875 (200)", "value": { "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875", "status": "completed", "blocks": [ "domain", "domain_validation" ], "counts": { "total": 3, "processed": 3, "succeeded": 3, "not_found": 0, "failed": 0, "site_unreachable": 0 }, "delivery": { "mode": "pull" }, "results_ready": true, "expires_at": "2026-10-15T07:09:32.659195Z", "created_at": "2026-09-15T07:07:47.705727Z", "finished_at": "2026-09-15T07:09:32.659195Z" } }, "jobs_status_queued_200": { "summary": "GET /v1/enrich/jobs/d99ba955-f280-4723-b49a-fbb3dd872875 (200)", "value": { "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875", "status": "queued", "blocks": [ "domain", "domain_validation" ], "counts": { "total": 3, "processed": 0, "succeeded": 0, "not_found": 0, "failed": 0, "site_unreachable": 0 }, "delivery": { "mode": "pull" }, "results_ready": false, "expires_at": null, "created_at": "2026-09-15T07:07:47.705727Z", "finished_at": null, "retry_after_ms": 1000 } }, "resolve_400_defer_live_store": { "summary": "GET /v1/resolve (400)", "value": { "detail": "defer_live=true cannot be combined with store=false: the live blocks are delivered through the stored job, so it has to be kept until you collect them." } }, "resolve_400_min_confidence": { "summary": "GET /v1/resolve (400)", "value": { "options": { "min_confidence": [ "Ensure this value is less than or equal to 1.0." ] } } }, "resolve_400_two_keys": { "summary": "GET /v1/resolve (400)", "value": { "detail": "Give exactly one of company_number, company_name, or domain." } }, "resolve_400_unknown_block": { "summary": "GET /v1/resolve (400)", "value": { "blocks": [ "Unknown block(s): not_a_block. Available: domain, related_company_domain, domain_validation, nature_of_business, registered_address, corporate_owners, controllers, charges, property, officers, company_identity, filing_status, registry_events, financials_filed, ultimate_owner, employees_filed, industry, contacts." ] } }, "resolve_400_validation_mode": { "summary": "GET /v1/resolve (400)", "value": { "options": { "validation": { "1": [ "\"psychic\" is not a valid choice." ] } } } }, "resolve_403_not_enabled": { "summary": "GET /v1/resolve (403)", "value": { "detail": "Not enabled for this account: company_summary.", "blocks": { "company_summary": { "status": "not_enabled", "reason": "no_entitlement" } } } }, "resolve_404_not_matched": { "summary": "GET /v1/resolve (404)", "value": { "detail": "not_matched" } }, "resolve_404_not_own_site": { "summary": "GET /v1/resolve (404)", "value": { "detail": "not_matched", "reason": "not_own_site", "host_type": "register" } }, "resolve_404_site_unreachable": { "summary": "GET /v1/resolve (404)", "value": { "detail": "not_matched", "reason": "site_unreachable", "site_lookup": { "reason": "site_unreachable", "domain": "zzqq-not-a-real-company-2026.co.uk", "final_url": null, "pages_read": [] } } }, "resolve_409_ambiguous": { "summary": "GET /v1/resolve (409)", "value": { "detail": "ambiguous_match", "candidates": [ { "company_number": "00445790", "company_name": "TESCO PLC" }, { "company_number": "00519500", "company_name": "TESCO STORES LIMITED" }, { "company_number": "08730224", "company_name": "TESCO SECRETARIES LIMITED" }, { "company_number": "00243011", "company_name": "TESCO HOLDINGS LIMITED" }, { "company_number": "04345023", "company_name": "TESCO FREETIME LIMITED" } ] } }, "resolve_429": { "summary": "GET /v1/resolve (429)", "description": "Past 60 resolves a minute on one key. The response also carries a Retry-After header in seconds.", "value": { "detail": "Request was throttled. Expected available in 1 second." } }, "resolve_progressive_first_200": { "summary": "GET /v1/resolve (200)", "description": "With defer_live=true, domain, property, subsidiaries and nature_of_business are answered at once; domain_validation opens the site and is pending.", "value": { "ref": "", "status": "pending", "blocks": { "domain": { "status": "available", "value": "hotelchocolat.com", "source": "cache" }, "domain_validation": { "status": "pending" }, "nature_of_business": { "status": "not_found", "reason": "no_description_on_file", "detail": { "website_verdict": { "domain": "hotelchocolat.com", "outcome": "accept", "score": 100, "confidence": 1, "checked_at": "2026-09-15T07:07:48Z", "auto_run": false, "served": false } } }, "property": { "status": "available", "value": { "title_count": 6, "tenure": [ "Freehold", "Leasehold" ], "postcodes": [ "PE29 7HA", "PE19 8JJ", "PE29 7DQ" ], "addresses": [ "Land lying to the west of Sallowbush Road, Huntingdon", "3 Redwongs Way, Huntingdon, (PE29 7HA)", "1a and, 2b Alpha Drive, Eaton Socon, St Neots (PE19 8JJ)", "Topper Cases Ltd, 1 Glebe Road, Huntingdon (PE29 7DQ)", "Land lying to the west of Sallowbush Road, Huntingdon", "Unit SU31, Block E/F, Southgate, Bath" ] }, "source": "hm_land_registry" }, "subsidiaries": { "status": "available", "value": { "subsidiaries": [ { "company_number": "10487072", "company_name": "RABOT 1745 LIMITED", "company_status": "Dissolved", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "ownership_band": "75–100%", "notified_on": "2017-10-30", "matched_on": "registration_number" }, { "company_number": "02174370", "company_name": "HOTEL CHOCOLAT CORPORATE LTD", "company_status": "Dissolved", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "ownership_band": "75–100%", "notified_on": "2016-04-06", "matched_on": "registration_number" } ], "count": 2, "active_count": 0 }, "source": "companies_house_psc", "as_of": "2017-10-30" } }, "pending_blocks": [ "domain_validation" ], "matched": { "company_number": "02805730", "company_name": "HOTEL CHOCOLAT LIMITED", "match_confidence": 1, "matched_on": "company_number" }, "job_id": "4d107210-fa63-49f6-be73-446f989a6f2e", "expires_at": null, "complete": false, "results_url": "https://api.getzorro.ai/v1/enrich/jobs/4d107210-fa63-49f6-be73-446f989a6f2e/results", "status_url": "https://api.getzorro.ai/v1/enrich/jobs/4d107210-fa63-49f6-be73-446f989a6f2e", "retry_after_ms": 1000 } }, "resolve_progressive_poll_200": { "summary": "GET /v1/enrich/jobs/4d107210-fa63-49f6-be73-446f989a6f2e/results (200)", "description": "A poll while domain_validation is still pending: results_ready false, retry_after_ms set.", "value": { "results": [ { "ref": "", "status": "pending", "blocks": { "domain": { "status": "available", "value": "hotelchocolat.com", "source": "cache" }, "domain_validation": { "status": "pending" }, "nature_of_business": { "status": "not_found", "reason": "no_description_on_file", "detail": { "website_verdict": { "domain": "hotelchocolat.com", "outcome": "accept", "score": 100, "confidence": 1, "checked_at": "2026-09-15T07:07:48Z", "auto_run": false, "served": false } } }, "property": { "status": "available", "value": { "title_count": 6, "tenure": [ "Freehold", "Leasehold" ], "postcodes": [ "PE29 7HA", "PE19 8JJ", "PE29 7DQ" ], "addresses": [ "Land lying to the west of Sallowbush Road, Huntingdon", "3 Redwongs Way, Huntingdon, (PE29 7HA)", "1a and, 2b Alpha Drive, Eaton Socon, St Neots (PE19 8JJ)", "Topper Cases Ltd, 1 Glebe Road, Huntingdon (PE29 7DQ)", "Land lying to the west of Sallowbush Road, Huntingdon", "Unit SU31, Block E/F, Southgate, Bath" ] }, "source": "hm_land_registry" }, "subsidiaries": { "status": "available", "value": { "subsidiaries": [ { "company_number": "10487072", "company_name": "RABOT 1745 LIMITED", "company_status": "Dissolved", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "ownership_band": "75–100%", "notified_on": "2017-10-30", "matched_on": "registration_number" }, { "company_number": "02174370", "company_name": "HOTEL CHOCOLAT CORPORATE LTD", "company_status": "Dissolved", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "ownership_band": "75–100%", "notified_on": "2016-04-06", "matched_on": "registration_number" } ], "count": 2, "active_count": 0 }, "source": "companies_house_psc", "as_of": "2017-10-30" } }, "pending_blocks": [ "domain_validation" ], "matched": { "company_number": "02805730", "company_name": "HOTEL CHOCOLAT LIMITED", "match_confidence": 1, "matched_on": "company_number" } } ], "next_cursor": null, "remaining": 0, "results_ready": false, "expires_at": null, "retry_after_ms": 1000 } }, "resolve_progressive_results_200": { "summary": "GET /v1/enrich/jobs/4d107210-fa63-49f6-be73-446f989a6f2e/results (200)", "description": "The same resolve collected from results_url once results_ready is true.", "value": { "results": [ { "ref": "", "status": "done", "blocks": { "domain": { "status": "available", "value": "hotelchocolat.com", "source": "cache", "final_url": "https://www.hotelchocolat.com/uk" }, "domain_validation": { "status": "available", "value": { "domain": "hotelchocolat.com", "dns_resolves": true, "email_deliverable": true, "site_live": true, "http_status": 200, "final_url": "https://www.hotelchocolat.com/uk", "director_check": "companies_house", "score": 100, "outcome": "accept", "checks": { "legal_name_exact": 0.5, "business_name": true, "same_postcode": true, "similar_postcode": true, "city_match": true, "county_match": true, "address_match": true, "director_match": false, "company_number": true, "other_company_number": false, "foreign_registration": false, "uk_domain": false, "phone_present": true, "generic_platform": false, "parked": false }, "contributions": { "legal_name_exact": 15, "business_name": 15, "same_postcode": 25, "similar_postcode": 8, "city_match": 10, "county_match": 5, "address_match": 15, "phone_present": 3, "company_number": 50 }, "reasons": [ "all checks passed" ] }, "source": "zorro_validator", "confidence": 1, "flagged_for_review": false, "detail": { "evidence": { "hard_matches": { "company_number": { "url": "https://www.hotelchocolat.com/uk/i/terms-and-conditions.html", "snippet": "…ngdom. Registered in England and Wales under company number 2805730. VAT number 945695766 (“Hotel Chocolat”) 2. Information Abo…" }, "postcode": { "url": "https://www.hotelchocolat.com/uk", "snippet": "…pp © Hotel Chocolat 2026. Mint House, Newark Close, Royston SG8 5HL, UK An Affiliate of Mars, Incorporated Terms & Conditions S…" }, "registered_address": { "url": "https://www.hotelchocolat.com/uk", "snippet": "…s Sign Up Follow Us Download Our App © Hotel Chocolat 2026. Mint House, Newark Close, Royston SG8 5HL, UK An Affiliate of Mars, In…" } }, "name_match": { "kind": "trading_name", "url": "https://www.hotelchocolat.com/uk", "snippet": "Luxury Chocolates | Chocolate Gifts & Hampers | Hotel Chocolat Skip to Content Help Help & Support FREE Standard Delivery…" } } } }, "nature_of_business": { "status": "not_found", "reason": "no_description_on_file", "detail": { "website_verdict": { "domain": "hotelchocolat.com", "outcome": "accept", "score": 100, "confidence": 1, "checked_at": "2026-09-15T07:07:48Z", "auto_run": false, "served": false } } }, "property": { "status": "available", "value": { "title_count": 6, "tenure": [ "Freehold", "Leasehold" ], "postcodes": [ "PE29 7HA", "PE19 8JJ", "PE29 7DQ" ], "addresses": [ "Land lying to the west of Sallowbush Road, Huntingdon", "3 Redwongs Way, Huntingdon, (PE29 7HA)", "1a and, 2b Alpha Drive, Eaton Socon, St Neots (PE19 8JJ)", "Topper Cases Ltd, 1 Glebe Road, Huntingdon (PE29 7DQ)", "Land lying to the west of Sallowbush Road, Huntingdon", "Unit SU31, Block E/F, Southgate, Bath" ] }, "source": "hm_land_registry" }, "subsidiaries": { "status": "available", "value": { "subsidiaries": [ { "company_number": "10487072", "company_name": "RABOT 1745 LIMITED", "company_status": "Dissolved", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "ownership_band": "75–100%", "notified_on": "2017-10-30", "matched_on": "registration_number" }, { "company_number": "02174370", "company_name": "HOTEL CHOCOLAT CORPORATE LTD", "company_status": "Dissolved", "natures_of_control": [ "ownership-of-shares-75-to-100-percent", "voting-rights-75-to-100-percent" ], "ownership_band": "75–100%", "notified_on": "2016-04-06", "matched_on": "registration_number" } ], "count": 2, "active_count": 0 }, "source": "companies_house_psc", "as_of": "2017-10-30" } }, "matched": { "company_number": "02805730", "company_name": "HOTEL CHOCOLAT LIMITED", "match_confidence": 1, "matched_on": "company_number" } } ], "next_cursor": null, "remaining": 0, "results_ready": true, "expires_at": "2026-10-15T07:16:26.303575Z" } }, "resolve_warning_200": { "summary": "GET /v1/resolve (200)", "description": "company_summary is not enabled for the key: the other block resolves, and one warning names the refused block.", "value": { "ref": "", "status": "done", "blocks": { "company_summary": { "status": "not_enabled", "reason": "no_entitlement" } }, "matched": { "company_number": "02805730", "company_name": "HOTEL CHOCOLAT LIMITED", "match_confidence": 1, "matched_on": "company_number" }, "job_id": "a223350b-c286-4562-a524-1239a575ebef", "expires_at": "2026-10-15T07:07:30.594324Z", "warnings": [ { "code": "blocks_not_enabled", "blocks": [ "company_summary" ], "detail": "Not enabled for your key: company_summary. Returned as not_enabled; every other block is unaffected." } ], "complete": true, "pending_blocks": [], "results_url": "https://api.getzorro.ai/v1/enrich/jobs/a223350b-c286-4562-a524-1239a575ebef/results", "status_url": "https://api.getzorro.ai/v1/enrich/jobs/a223350b-c286-4562-a524-1239a575ebef" } }, "usage_400_granularity": { "summary": "GET /v1/usage (400)", "value": { "detail": "`granularity` is one of: block, day." } }, "usage_day_200": { "summary": "GET /v1/usage (200)", "value": { "range": { "from": "2026-09-14", "to": "2026-09-15" }, "granularity": "day", "pricing_status": "not_priced", "pricing_note": "Counts only; amounts appear once contract prices are set.", "days": [ { "date": "2026-09-14", "events": 0, "billed_events": 0, "outcomes": {}, "blocks": {} }, { "date": "2026-09-15", "events": 6, "billed_events": 6, "outcomes": { "delivered": 6 }, "blocks": { "domain": 3, "domain_validation": 3 } } ], "totals": { "events": 6, "billed_events": 6 }, "billing_rule": "Charged once per row per block, and only where the block delivered a value. not_found, ambiguous_match, not_enabled, provider errors and rows skipped by a cancel are recorded at zero.", "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875" } }, "usage_job_200": { "summary": "GET /v1/usage (200)", "description": "Until contract prices are set up for the account, usage shows counts only.", "value": { "range": { "from": "2026-08-17", "to": "2026-09-15" }, "granularity": "block", "pricing_status": "not_priced", "pricing_note": "Counts only; amounts appear once contract prices are set.", "blocks": [ { "block": "domain", "events": 3, "billed_events": 3, "outcomes": { "delivered": 3 } }, { "block": "domain_validation", "events": 3, "billed_events": 3, "outcomes": { "delivered": 3 } } ], "totals": { "events": 6, "billed_events": 6, "rows": 6, "billed_rows": 6, "invoiceable": false }, "billing_rule": "Charged once per row per block, and only where the block delivered a value. not_found, ambiguous_match, not_enabled, provider errors and rows skipped by a cancel are recorded at zero.", "job_id": "d99ba955-f280-4723-b49a-fbb3dd872875" } }, "whoami_200": { "summary": "GET /v1/whoami (200)", "value": { "key_id": "abcdefghjkmn", "name": "Example Bank production", "environment": "live", "scopes": [ "read", "enrich" ], "account": { "id": 1234, "email": "api-owner@example.com" }, "blocks": [ { "key": "domain", "availability": "available", "tier": "core" }, { "key": "related_company_domain", "availability": "available", "tier": "premium" }, { "key": "domain_validation", "availability": "available", "tier": "core" }, { "key": "nature_of_business", "availability": "available", "tier": "premium" }, { "key": "registered_address", "availability": "available", "tier": "core" }, { "key": "corporate_owners", "availability": "available", "tier": "core" }, { "key": "controllers", "availability": "available", "tier": "core" }, { "key": "charges", "availability": "available", "tier": "core" }, { "key": "property", "availability": "available", "tier": "premium" }, { "key": "officers", "availability": "available", "tier": "core" }, { "key": "company_identity", "availability": "available", "tier": "core" }, { "key": "filing_status", "availability": "available", "tier": "core" }, { "key": "registry_events", "availability": "available", "tier": "core" }, { "key": "financials_filed", "availability": "available", "tier": "premium" }, { "key": "ultimate_owner", "availability": "available", "tier": "premium" }, { "key": "employees_filed", "availability": "available", "tier": "premium" }, { "key": "industry", "availability": "available", "tier": "core" }, { "key": "contacts", "availability": "available", "tier": "premium" }, { "key": "signals", "availability": "available", "tier": "premium" }, { "key": "news_signals", "availability": "available", "tier": "premium" }, { "key": "financials_live", "availability": "available", "tier": "premium" }, { "key": "employees_live", "availability": "available", "tier": "premium" }, { "key": "web_traffic", "availability": "available", "tier": "premium" }, { "key": "web_presence", "availability": "available", "tier": "premium" }, { "key": "technologies", "availability": "available", "tier": "premium" }, { "key": "employees", "availability": "available", "tier": "premium" }, { "key": "planning", "availability": "available", "tier": "premium" }, { "key": "financial_benchmarks", "availability": "available", "tier": "premium" }, { "key": "revenue_estimate", "availability": "available", "tier": "premium" }, { "key": "scores", "availability": "available", "tier": "premium" }, { "key": "funding", "availability": "available", "tier": "premium" }, { "key": "trading_address", "availability": "available", "tier": "premium" }, { "key": "subsidiaries", "availability": "available", "tier": "premium" }, { "key": "firmographics", "availability": "available", "tier": "premium" }, { "key": "comparables", "availability": "available", "tier": "premium" }, { "key": "business_intelligence", "availability": "available", "tier": "premium" }, { "key": "company_summary", "availability": "not_enabled", "tier": "premium" } ], "blocks_enabled_count": 36, "blocks_total": 37, "limits": { "max_rows_per_job": 250000, "max_rows_per_job_source": "default", "rate_limits": { "requests_per_minute": 600, "resolve_per_minute": 60 }, "expires_at": null }, "docs": { "url": "https://getzorro.ai/docs/api", "openapi": "/v1/openapi.json", "catalog": "/v1/blocks" } } }, "whoami_401_invalid": { "summary": "GET /v1/whoami (401)", "value": { "detail": "Invalid API key." } }, "whoami_401_missing": { "summary": "GET /v1/whoami (401)", "value": { "detail": "Authentication credentials were not provided." } } } } }