{ "info": { "name": "Zorro API v1", "description": "Generated from https://getzorro.ai/docs/api/openapi.json. Set the ZORRO_API_KEY collection variable to your key; it is sent as a Bearer token. Resolve and job creation store job_id for the job requests.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{ZORRO_API_KEY}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://api.getzorro.ai" }, { "key": "ZORRO_API_KEY", "value": "", "description": "Your API key. Never commit it." }, { "key": "job_id", "value": "" } ], "item": [ { "name": "Spec", "item": [ { "name": "Fetch this description", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/openapi.json", "host": [ "{{baseUrl}}" ], "path": [ "v1", "openapi.json" ] }, "description": "This description, from the host it describes. The response is the document itself, the same one published at https://getzorro.ai/docs/api/openapi.json.\n\nNo key is needed, and the answer is the same for every account. `/v1/openapi` answers identically." } } ] }, { "name": "Key", "item": [ { "name": "Check a key and see its access", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/whoami", "host": [ "{{baseUrl}}" ], "path": [ "v1", "whoami" ] }, "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`." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/whoami", "host": [ "{{baseUrl}}" ], "path": [ "v1", "whoami" ] }, "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`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"key_id\": \"abcdefghjkmn\",\n \"name\": \"Example Bank production\",\n \"environment\": \"live\",\n \"scopes\": [\n \"read\",\n \"enrich\"\n ],\n \"account\": {\n \"id\": 1234,\n \"email\": \"api-owner@example.com\"\n },\n \"blocks\": [\n {\n \"key\": \"domain\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"related_company_domain\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"domain_validation\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"nature_of_business\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"registered_address\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"corporate_owners\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"controllers\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"charges\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"property\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"officers\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"company_identity\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"filing_status\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"registry_events\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"financials_filed\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"ultimate_owner\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"employees_filed\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"industry\",\n \"availability\": \"available\",\n \"tier\": \"core\"\n },\n {\n \"key\": \"contacts\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"signals\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"news_signals\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"financials_live\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"employees_live\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"web_traffic\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"web_presence\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"technologies\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"employees\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"planning\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"financial_benchmarks\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"revenue_estimate\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"scores\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"funding\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"trading_address\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"subsidiaries\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"firmographics\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"comparables\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"business_intelligence\",\n \"availability\": \"available\",\n \"tier\": \"premium\"\n },\n {\n \"key\": \"company_summary\",\n \"availability\": \"not_enabled\",\n \"tier\": \"premium\"\n }\n ],\n \"blocks_enabled_count\": 36,\n \"blocks_total\": 37,\n \"limits\": {\n \"max_rows_per_job\": 250000,\n \"max_rows_per_job_source\": \"default\",\n \"rate_limits\": {\n \"requests_per_minute\": 600,\n \"resolve_per_minute\": 60\n },\n \"expires_at\": null\n },\n \"docs\": {\n \"url\": \"https://getzorro.ai/docs/api\",\n \"openapi\": \"/v1/openapi.json\",\n \"catalog\": \"/v1/blocks\"\n }\n}", "_postman_previewlanguage": "json" } ] }, { "name": "List the block catalogue", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/blocks", "host": [ "{{baseUrl}}" ], "path": [ "v1", "blocks" ] }, "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`." } } ] }, { "name": "Resolve", "item": [ { "name": "Resolve one company", "request": { "method": "GET", "header": [ { "key": "X-Idempotency-Key", "value": "", "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.", "disabled": true } ], "url": { "raw": "{{baseUrl}}/v1/resolve?company_number=02805730&blocks=company_identity,registered_address,officers,controllers&defer_live=true", "host": [ "{{baseUrl}}" ], "path": [ "v1", "resolve" ], "query": [ { "key": "company_number", "value": "02805730", "description": "This is the Companies House number. Give exactly one of company_number, company_name or domain.", "disabled": false }, { "key": "company_name", "value": "", "description": "This is the name as registered at Companies House, for example GYMSHARK LTD. It is matched as registered: \"Gymshark Limited\" does not find GYMSHARK LTD. Prefer company_number or domain when you have them. More than one live match answers 409 with candidates.", "disabled": true }, { "key": "domain", "value": "", "description": "Provide a bare host or URL. A register, directory, social or site-builder host answers 404 not_own_site.", "disabled": true }, { "key": "blocks", "value": "company_identity,registered_address,officers,controllers", "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.", "disabled": false }, { "key": "validation", "value": "", "description": "The domain_validation modes are none, rules, live, officers, ai. The default modes are rules,live.", "disabled": true }, { "key": "min_confidence", "value": "", "description": "Set your threshold from 0 to 1. The default is 0.5.", "disabled": true }, { "key": "defer_live", "value": "true", "description": "When true, the response is 200 at once with the blocks we already hold; live blocks are pending and collected from results_url. This cannot be combined with wait=false or store=false.", "disabled": false }, { "key": "wait", "value": "", "description": "When true, the row is resolved inside the request and the response is 200 with every block (the call's behaviour before 8 Oct 2026). Without it the row is queued and the response is 202 with the job and results_url. Without a discover parameter, wait=true searches for nothing.", "disabled": true }, { "key": "store", "value": "", "description": "When false, the row is not kept for later reads (expires_at null, stored false). It needs wait=true; without it the response is 400, because a queued row has to be kept until you collect it.", "disabled": true }, { "key": "discover", "value": "", "description": "The blocks to look up live when the company has no value on file: domain (search the web for the website), nature_of_business and news_signals. Without this parameter it defaults to domain and news_signals, as on a job, on every call except wait=true, where it is off and a company with no website on file answers no_domain_found. news_signals is looked up only when it is in blocks. Pass discover= (empty) to look up nothing.", "disabled": true }, { "key": "max_live_lookups", "value": "", "description": "This sets the number of website searches allowed and defaults to 1 when discover is given or defaulted.", "disabled": true }, { "key": "ref", "value": "", "description": "This is your reference, which is echoed back.", "disabled": true }, { "key": "read_accounts_pdf", "value": "", "description": "For financials_live, this reads PDF-only accounts we have not read yet (a paid model call, slower). It is off by default; readings we already hold are served by financials_filed without it.", "disabled": true }, { "key": "web_search", "value": "", "description": "This is a Premium option enabled per account.", "disabled": true }, { "key": "google_business", "value": "", "description": "For trading_address, this adds the listing check.", "disabled": true }, { "key": "contact_roles", "value": "", "description": "For contacts, the values are owner, director, finance, operations, in order of preference.", "disabled": true }, { "key": "max_contacts", "value": "", "description": "For contacts, use 1 to 5; the default is 3.", "disabled": true }, { "key": "verify_emails", "value": "", "description": "For contacts, the default is true.", "disabled": true }, { "key": "contacts_lookup", "value": "", "description": "For contacts, use cached_only or live; the default is live.", "disabled": true }, { "key": "include_phone", "value": "", "description": "For contacts, this returns a phone number per person. With contacts_lookup=live it cannot be combined with wait=true (400); queued or with defer_live=true, the lookup runs to completion.", "disabled": true }, { "key": "include_linkedin", "value": "", "description": "For contacts, the default is true.", "disabled": true } ] }, "description": "Send one company. By default the row is queued like a one-row job: the response is 202 with the job, and the row is collected from results_url (GET /v1/enrich/jobs/{job_id}/results) once results_ready is true. Nothing is computed while the request is open. The limit is 60 requests a minute per key.\n\nWith defer_live=true the response is 200 at once with every block we already hold; blocks still being checked are {\"status\":\"pending\"} and are collected from results_url. With wait=true the row is resolved inside the request and the response is 200 with every block; use it for a handful of blocks, not for live work.\n\nWithout a discover parameter a website is searched for when none is on file, as on a job, on every call except wait=true; there, pass discover=domain for that.\n\nRequired scope: `enrich`." }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "if (body && body.job_id) { pm.collectionVariables.set(\"job_id\", body.job_id); }" ] } } ], "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [ { "key": "X-Idempotency-Key", "value": "", "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.", "disabled": true } ], "url": { "raw": "{{baseUrl}}/v1/resolve?company_number=02805730&blocks=company_identity,registered_address,officers,controllers&defer_live=true", "host": [ "{{baseUrl}}" ], "path": [ "v1", "resolve" ], "query": [ { "key": "company_number", "value": "02805730", "description": "This is the Companies House number. Give exactly one of company_number, company_name or domain.", "disabled": false }, { "key": "company_name", "value": "", "description": "This is the name as registered at Companies House, for example GYMSHARK LTD. It is matched as registered: \"Gymshark Limited\" does not find GYMSHARK LTD. Prefer company_number or domain when you have them. More than one live match answers 409 with candidates.", "disabled": true }, { "key": "domain", "value": "", "description": "Provide a bare host or URL. A register, directory, social or site-builder host answers 404 not_own_site.", "disabled": true }, { "key": "blocks", "value": "company_identity,registered_address,officers,controllers", "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.", "disabled": false }, { "key": "validation", "value": "", "description": "The domain_validation modes are none, rules, live, officers, ai. The default modes are rules,live.", "disabled": true }, { "key": "min_confidence", "value": "", "description": "Set your threshold from 0 to 1. The default is 0.5.", "disabled": true }, { "key": "defer_live", "value": "true", "description": "When true, the response is 200 at once with the blocks we already hold; live blocks are pending and collected from results_url. This cannot be combined with wait=false or store=false.", "disabled": false }, { "key": "wait", "value": "", "description": "When true, the row is resolved inside the request and the response is 200 with every block (the call's behaviour before 8 Oct 2026). Without it the row is queued and the response is 202 with the job and results_url. Without a discover parameter, wait=true searches for nothing.", "disabled": true }, { "key": "store", "value": "", "description": "When false, the row is not kept for later reads (expires_at null, stored false). It needs wait=true; without it the response is 400, because a queued row has to be kept until you collect it.", "disabled": true }, { "key": "discover", "value": "", "description": "The blocks to look up live when the company has no value on file: domain (search the web for the website), nature_of_business and news_signals. Without this parameter it defaults to domain and news_signals, as on a job, on every call except wait=true, where it is off and a company with no website on file answers no_domain_found. news_signals is looked up only when it is in blocks. Pass discover= (empty) to look up nothing.", "disabled": true }, { "key": "max_live_lookups", "value": "", "description": "This sets the number of website searches allowed and defaults to 1 when discover is given or defaulted.", "disabled": true }, { "key": "ref", "value": "", "description": "This is your reference, which is echoed back.", "disabled": true }, { "key": "read_accounts_pdf", "value": "", "description": "For financials_live, this reads PDF-only accounts we have not read yet (a paid model call, slower). It is off by default; readings we already hold are served by financials_filed without it.", "disabled": true }, { "key": "web_search", "value": "", "description": "This is a Premium option enabled per account.", "disabled": true }, { "key": "google_business", "value": "", "description": "For trading_address, this adds the listing check.", "disabled": true }, { "key": "contact_roles", "value": "", "description": "For contacts, the values are owner, director, finance, operations, in order of preference.", "disabled": true }, { "key": "max_contacts", "value": "", "description": "For contacts, use 1 to 5; the default is 3.", "disabled": true }, { "key": "verify_emails", "value": "", "description": "For contacts, the default is true.", "disabled": true }, { "key": "contacts_lookup", "value": "", "description": "For contacts, use cached_only or live; the default is live.", "disabled": true }, { "key": "include_phone", "value": "", "description": "For contacts, this returns a phone number per person. With contacts_lookup=live it cannot be combined with wait=true (400); queued or with defer_live=true, the lookup runs to completion.", "disabled": true }, { "key": "include_linkedin", "value": "", "description": "For contacts, the default is true.", "disabled": true } ] }, "description": "Send one company. By default the row is queued like a one-row job: the response is 202 with the job, and the row is collected from results_url (GET /v1/enrich/jobs/{job_id}/results) once results_ready is true. Nothing is computed while the request is open. The limit is 60 requests a minute per key.\n\nWith defer_live=true the response is 200 at once with every block we already hold; blocks still being checked are {\"status\":\"pending\"} and are collected from results_url. With wait=true the row is resolved inside the request and the response is 200 with every block; use it for a handful of blocks, not for live work.\n\nWithout a discover parameter a website is searched for when none is on file, as on a job, on every call except wait=true; there, pass discover=domain for that.\n\nRequired scope: `enrich`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ref\": \"\",\n \"status\": \"pending\",\n \"blocks\": {\n \"domain\": {\n \"status\": \"available\",\n \"value\": \"hotelchocolat.com\",\n \"source\": \"cache\"\n },\n \"domain_validation\": {\n \"status\": \"pending\"\n },\n \"nature_of_business\": {\n \"status\": \"not_found\",\n \"reason\": \"no_description_on_file\",\n \"detail\": {\n \"website_verdict\": {\n \"domain\": \"hotelchocolat.com\",\n \"outcome\": \"accept\",\n \"score\": 100,\n \"confidence\": 1,\n \"checked_at\": \"2026-09-15T07:07:48Z\",\n \"auto_run\": false,\n \"served\": false\n }\n }\n },\n \"property\": {\n \"status\": \"available\",\n \"value\": {\n \"title_count\": 6,\n \"tenure\": [\n \"Freehold\",\n \"Leasehold\"\n ],\n \"postcodes\": [\n \"PE29 7HA\",\n \"PE19 8JJ\",\n \"PE29 7DQ\"\n ],\n \"addresses\": [\n \"Land lying to the west of Sallowbush Road, Huntingdon\",\n \"3 Redwongs Way, Huntingdon, (PE29 7HA)\",\n \"1a and, 2b Alpha Drive, Eaton Socon, St Neots (PE19 8JJ)\",\n \"Topper Cases Ltd, 1 Glebe Road, Huntingdon (PE29 7DQ)\",\n \"Land lying to the west of Sallowbush Road, Huntingdon\",\n \"Unit SU31, Block E/F, Southgate, Bath\"\n ]\n },\n \"source\": \"hm_land_registry\"\n },\n \"subsidiaries\": {\n \"status\": \"available\",\n \"value\": {\n \"subsidiaries\": [\n {\n \"company_number\": \"10487072\",\n \"company_name\": \"RABOT 1745 LIMITED\",\n \"company_status\": \"Dissolved\",\n \"natures_of_control\": [\n \"ownership-of-shares-75-to-100-percent\",\n \"voting-rights-75-to-100-percent\"\n ],\n \"ownership_band\": \"75–100%\",\n \"notified_on\": \"2017-10-30\",\n \"matched_on\": \"registration_number\"\n },\n {\n \"company_number\": \"02174370\",\n \"company_name\": \"HOTEL CHOCOLAT CORPORATE LTD\",\n \"company_status\": \"Dissolved\",\n \"natures_of_control\": [\n \"ownership-of-shares-75-to-100-percent\",\n \"voting-rights-75-to-100-percent\"\n ],\n \"ownership_band\": \"75–100%\",\n \"notified_on\": \"2016-04-06\",\n \"matched_on\": \"registration_number\"\n }\n ],\n \"count\": 2,\n \"active_count\": 0\n },\n \"source\": \"companies_house_psc\",\n \"as_of\": \"2017-10-30\"\n }\n },\n \"pending_blocks\": [\n \"domain_validation\"\n ],\n \"matched\": {\n \"company_number\": \"02805730\",\n \"company_name\": \"HOTEL CHOCOLAT LIMITED\",\n \"match_confidence\": 1,\n \"matched_on\": \"company_number\"\n },\n \"job_id\": \"4d107210-fa63-49f6-be73-446f989a6f2e\",\n \"expires_at\": null,\n \"complete\": false,\n \"results_url\": \"https://api.getzorro.ai/v1/enrich/jobs/4d107210-fa63-49f6-be73-446f989a6f2e/results\",\n \"status_url\": \"https://api.getzorro.ai/v1/enrich/jobs/4d107210-fa63-49f6-be73-446f989a6f2e\",\n \"retry_after_ms\": 1000\n}", "_postman_previewlanguage": "json" } ] } ] }, { "name": "Jobs", "item": [ { "name": "Submit a list as a job", "request": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "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.", "disabled": true }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs" ] }, "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`.", "body": { "mode": "raw", "raw": "{\n \"rows\": [\n {\n \"ref\": \"crm-1001\",\n \"company_number\": \"02805730\"\n },\n {\n \"ref\": \"crm-1002\",\n \"company_number\": \"08130873\"\n },\n {\n \"ref\": \"crm-1003\",\n \"company_number\": \"07706156\"\n }\n ],\n \"blocks\": [\n \"domain\",\n \"domain_validation\"\n ],\n \"options\": {\n \"validation\": [\n \"rules\",\n \"live\"\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "if (body && body.job_id) { pm.collectionVariables.set(\"job_id\", body.job_id); }" ] } } ], "response": [ { "name": "202 example", "originalRequest": { "method": "POST", "header": [ { "key": "X-Idempotency-Key", "value": "", "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.", "disabled": true }, { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs" ] }, "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`.", "body": { "mode": "raw", "raw": "{\n \"rows\": [\n {\n \"ref\": \"crm-1001\",\n \"company_number\": \"02805730\"\n },\n {\n \"ref\": \"crm-1002\",\n \"company_number\": \"08130873\"\n },\n {\n \"ref\": \"crm-1003\",\n \"company_number\": \"07706156\"\n }\n ],\n \"blocks\": [\n \"domain\",\n \"domain_validation\"\n ],\n \"options\": {\n \"validation\": [\n \"rules\",\n \"live\"\n ]\n }\n}", "options": { "raw": { "language": "json" } } } }, "status": "202", "code": 202, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"job_id\": \"d99ba955-f280-4723-b49a-fbb3dd872875\",\n \"status\": \"queued\",\n \"blocks\": [\n \"domain\",\n \"domain_validation\"\n ],\n \"counts\": {\n \"total\": 3,\n \"processed\": 0,\n \"succeeded\": 0,\n \"not_found\": 0,\n \"failed\": 0,\n \"site_unreachable\": 0\n },\n \"delivery\": {\n \"mode\": \"pull\"\n },\n \"results_ready\": false,\n \"expires_at\": null,\n \"created_at\": \"2026-09-15T07:07:47.705727Z\",\n \"finished_at\": null\n}", "_postman_previewlanguage": "json" } ] }, { "name": "Get a job's status", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}" ] }, "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`." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}" ] }, "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`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"job_id\": \"d99ba955-f280-4723-b49a-fbb3dd872875\",\n \"status\": \"completed\",\n \"blocks\": [\n \"domain\",\n \"domain_validation\"\n ],\n \"counts\": {\n \"total\": 3,\n \"processed\": 3,\n \"succeeded\": 3,\n \"not_found\": 0,\n \"failed\": 0,\n \"site_unreachable\": 0\n },\n \"delivery\": {\n \"mode\": \"pull\"\n },\n \"results_ready\": true,\n \"expires_at\": \"2026-10-15T07:09:32.659195Z\",\n \"created_at\": \"2026-09-15T07:07:47.705727Z\",\n \"finished_at\": \"2026-09-15T07:09:32.659195Z\"\n}", "_postman_previewlanguage": "json" } ] }, { "name": "Page through a job's rows", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}/results?limit=100", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}", "results" ], "query": [ { "key": "cursor", "value": "", "description": "Use next_cursor from the previous page. Omit it to start.", "disabled": true }, { "key": "limit", "value": "100", "description": "The page size defaults to 100 and is at most 1000. A missing or invalid value uses the default.", "disabled": false } ] }, "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`." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}/results?limit=100", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}", "results" ], "query": [ { "key": "cursor", "value": "", "description": "Use next_cursor from the previous page. Omit it to start.", "disabled": true }, { "key": "limit", "value": "100", "description": "The page size defaults to 100 and is at most 1000. A missing or invalid value uses the default.", "disabled": false } ] }, "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`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"results\": [\n {\n \"ref\": \"crm-1001\",\n \"status\": \"done\",\n \"blocks\": {\n \"domain\": {\n \"status\": \"available\",\n \"value\": \"hotelchocolat.com\",\n \"source\": \"cache\",\n \"final_url\": \"https://www.hotelchocolat.com/uk\"\n },\n \"domain_validation\": {\n \"status\": \"available\",\n \"value\": {\n \"domain\": \"hotelchocolat.com\",\n \"dns_resolves\": true,\n \"email_deliverable\": true,\n \"site_live\": true,\n \"http_status\": 200,\n \"final_url\": \"https://www.hotelchocolat.com/uk\",\n \"director_check\": \"companies_house\",\n \"score\": 100,\n \"outcome\": \"accept\",\n \"checks\": {\n \"legal_name_exact\": 0.5,\n \"business_name\": true,\n \"same_postcode\": true,\n \"similar_postcode\": true,\n \"city_match\": true,\n \"county_match\": true,\n \"address_match\": true,\n \"director_match\": false,\n \"company_number\": true,\n \"other_company_number\": false,\n \"foreign_registration\": false,\n \"uk_domain\": false,\n \"phone_present\": true,\n \"generic_platform\": false,\n \"parked\": false\n },\n \"contributions\": {\n \"legal_name_exact\": 15,\n \"business_name\": 15,\n \"same_postcode\": 25,\n \"similar_postcode\": 8,\n \"city_match\": 10,\n \"county_match\": 5,\n \"address_match\": 15,\n \"phone_present\": 3,\n \"company_number\": 50\n },\n \"reasons\": [\n \"all checks passed\"\n ]\n },\n \"source\": \"zorro_validator\",\n \"confidence\": 1,\n \"flagged_for_review\": false,\n \"detail\": {\n \"evidence\": {\n \"hard_matches\": {\n \"company_number\": {\n \"url\": \"https://www.hotelchocolat.com/uk/i/terms-and-conditions.html\",\n \"snippet\": \"…ngdom. Registered in England and Wales under company number 2805730. VAT number 945695766 (“Hotel Chocolat”) 2. Information Abo…\"\n },\n \"postcode\": {\n \"url\": \"https://www.hotelchocolat.com/uk\",\n \"snippet\": \"…pp © Hotel Chocolat 2026. Mint House, Newark Close, Royston SG8 5HL, UK An Affiliate of Mars, Incorporated Terms & Conditions S…\"\n },\n \"registered_address\": {\n \"url\": \"https://www.hotelchocolat.com/uk\",\n \"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…\"\n }\n },\n \"name_match\": {\n \"kind\": \"trading_name\",\n \"url\": \"https://www.hotelchocolat.com/uk\",\n \"snippet\": \"Luxury Chocolates | Chocolate Gifts & Hampers | Hotel Chocolat Skip to Content Help Help & Support FREE Standard Delivery…\"\n }\n }\n }\n }\n },\n \"matched\": {\n \"company_number\": \"02805730\",\n \"company_name\": \"HOTEL CHOCOLAT LIMITED\",\n \"match_confidence\": 1,\n \"matched_on\": \"company_number\"\n }\n },\n {\n \"ref\": \"crm-1002\",\n \"status\": \"done\",\n \"blocks\": {\n \"domain\": {\n \"status\": \"available\",\n \"value\": \"gymshark.com\",\n \"source\": \"cache\",\n \"final_url\": \"https://www.gymshark.com/\"\n },\n \"domain_validation\": {\n \"status\": \"available\",\n \"value\": {\n \"domain\": \"gymshark.com\",\n \"dns_resolves\": true,\n \"email_deliverable\": true,\n \"site_live\": true,\n \"http_status\": 200,\n \"final_url\": \"https://www.gymshark.com/\",\n \"director_check\": \"companies_house\",\n \"score\": 95,\n \"outcome\": \"accept\",\n \"checks\": {\n \"legal_name_exact\": true,\n \"business_name\": true,\n \"same_postcode\": false,\n \"similar_postcode\": false,\n \"city_match\": true,\n \"county_match\": false,\n \"address_match\": true,\n \"director_match\": true,\n \"company_number\": false,\n \"other_company_number\": false,\n \"foreign_registration\": false,\n \"uk_domain\": false,\n \"phone_present\": false,\n \"generic_platform\": false,\n \"parked\": false\n },\n \"contributions\": {\n \"legal_name_exact\": 30,\n \"business_name\": 15,\n \"city_match\": 10,\n \"address_match\": 15,\n \"director_match\": 25\n },\n \"reasons\": [\n \"all checks passed\"\n ]\n },\n \"source\": \"zorro_validator\",\n \"confidence\": 0.95,\n \"flagged_for_review\": false,\n \"detail\": {\n \"evidence\": {\n \"hard_matches\": {\n \"director\": {\n \"url\": \"https://www.gymshark.com/pages/about-us\",\n \"snippet\": \"…e do today to prepare for tomorrow. Gymshark is led by: Ben Francis - Founder & Chief Executive Officer Noel Mack - Chief Brand…\",\n \"surname\": \"francis\"\n }\n },\n \"name_match\": {\n \"kind\": \"legal_name\",\n \"url\": \"https://www.gymshark.com/pages/terms-and-conditions\",\n \"snippet\": \"…Language Selector dropdown English English Español © 2026 | Gymshark Limited | All Rights Reserved. | We Do Gym.\"\n }\n }\n }\n }\n },\n \"matched\": {\n \"company_number\": \"08130873\",\n \"company_name\": \"GYMSHARK LTD\",\n \"match_confidence\": 1,\n \"matched_on\": \"company_number\"\n }\n }\n ],\n \"next_cursor\": \"eyJzZXEiOjJ9\",\n \"remaining\": 1,\n \"results_ready\": true,\n \"expires_at\": \"2026-10-15T07:09:32.659195Z\"\n}", "_postman_previewlanguage": "json" } ] }, { "name": "Page through a job's quarantined rows", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}/errors?limit=100", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}", "errors" ], "query": [ { "key": "cursor", "value": "", "description": "Use next_cursor from the previous page. Omit it to start.", "disabled": true }, { "key": "limit", "value": "100", "description": "The page size defaults to 100 and is at most 1000. A missing or invalid value uses the default.", "disabled": false } ] }, "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`." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}/errors?limit=100", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}", "errors" ], "query": [ { "key": "cursor", "value": "", "description": "Use next_cursor from the previous page. Omit it to start.", "disabled": true }, { "key": "limit", "value": "100", "description": "The page size defaults to 100 and is at most 1000. A missing or invalid value uses the default.", "disabled": false } ] }, "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`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"errors\": [],\n \"next_cursor\": null,\n \"retryable_count\": 0,\n \"expires_at\": \"2026-10-15T07:09:32.659195Z\"\n}", "_postman_previewlanguage": "json" } ] }, { "name": "Cancel a job", "request": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}", "cancel" ] }, "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`." }, "response": [ { "name": "200 example", "originalRequest": { "method": "POST", "header": [], "url": { "raw": "{{baseUrl}}/v1/enrich/jobs/{{job_id}}/cancel", "host": [ "{{baseUrl}}" ], "path": [ "v1", "enrich", "jobs", "{{job_id}}", "cancel" ] }, "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`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"job_id\": \"d99ba955-f280-4723-b49a-fbb3dd872875\",\n \"status\": \"completed\",\n \"blocks\": [\n \"domain\",\n \"domain_validation\"\n ],\n \"counts\": {\n \"total\": 3,\n \"processed\": 3,\n \"succeeded\": 3,\n \"not_found\": 0,\n \"failed\": 0,\n \"site_unreachable\": 0\n },\n \"delivery\": {\n \"mode\": \"pull\"\n },\n \"results_ready\": true,\n \"expires_at\": \"2026-10-15T07:09:32.659195Z\",\n \"created_at\": \"2026-09-15T07:07:47.705727Z\",\n \"finished_at\": \"2026-09-15T07:09:32.659195Z\"\n}", "_postman_previewlanguage": "json" } ] } ] }, { "name": "Usage", "item": [ { "name": "Usage by block or by day", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/usage?", "host": [ "{{baseUrl}}" ], "path": [ "v1", "usage" ], "query": [ { "key": "from", "value": "", "description": "This is the first day, in YYYY-MM-DD format and UTC.", "disabled": true }, { "key": "to", "value": "", "description": "This is the last day, inclusive. The default is today.", "disabled": true }, { "key": "granularity", "value": "", "description": "Use block (default) or day.", "disabled": true }, { "key": "job_id", "value": "", "description": "Narrow to one job.", "disabled": true } ] }, "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`." }, "response": [ { "name": "200 example", "originalRequest": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/v1/usage?", "host": [ "{{baseUrl}}" ], "path": [ "v1", "usage" ], "query": [ { "key": "from", "value": "", "description": "This is the first day, in YYYY-MM-DD format and UTC.", "disabled": true }, { "key": "to", "value": "", "description": "This is the last day, inclusive. The default is today.", "disabled": true }, { "key": "granularity", "value": "", "description": "Use block (default) or day.", "disabled": true }, { "key": "job_id", "value": "", "description": "Narrow to one job.", "disabled": true } ] }, "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`." }, "status": "200", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"range\": {\n \"from\": \"2026-09-14\",\n \"to\": \"2026-09-15\"\n },\n \"granularity\": \"day\",\n \"pricing_status\": \"not_priced\",\n \"pricing_note\": \"Counts only; amounts appear once contract prices are set.\",\n \"days\": [\n {\n \"date\": \"2026-09-14\",\n \"events\": 0,\n \"billed_events\": 0,\n \"outcomes\": {},\n \"blocks\": {}\n },\n {\n \"date\": \"2026-09-15\",\n \"events\": 6,\n \"billed_events\": 6,\n \"outcomes\": {\n \"delivered\": 6\n },\n \"blocks\": {\n \"domain\": 3,\n \"domain_validation\": 3\n }\n }\n ],\n \"totals\": {\n \"events\": 6,\n \"billed_events\": 6\n },\n \"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.\",\n \"job_id\": \"d99ba955-f280-4723-b49a-fbb3dd872875\"\n}", "_postman_previewlanguage": "json" } ] } ] } ] }