{ "openapi": "3.1.0", "info": { "title": "Daybreak Leads API", "description": "Company signals from official filings: UK incorporations (Companies House) and US funding filings (SEC Form D). Every signal links to its filing.", "version": "1.0.0" }, "paths": { "/v1/companies/{id}": { "get": { "tags": [ "Companies" ], "operationId": "get_company", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/companies/{id}/website-corrections": { "post": { "tags": [ "Companies" ], "operationId": "correct_website", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebsiteCorrectionInput" } } }, "required": true }, "responses": { "202": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/companies/{id}/website-search": { "post": { "tags": [ "Companies" ], "operationId": "find_website", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyWebsite" } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyWebsite" } } } }, "404": { "description": "" }, "429": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/contact-searches": { "get": { "tags": [ "Contacts" ], "operationId": "search_log", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearchLog" } } } } }, "security": [ { "bearer": [] } ] } }, "/v1/contact-searches/{id}": { "get": { "tags": [ "Contacts" ], "operationId": "get_contact_search", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearch" } } } }, "404": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/contacts/access": { "get": { "tags": [ "Contacts" ], "operationId": "contacts_access", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsAccess" } } } } } } }, "/v1/contacts/export": { "get": { "tags": [ "Contacts" ], "operationId": "export_contacts", "responses": { "200": { "description": "", "content": { "text/csv": {} } }, "403": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/contacts/terms": { "post": { "tags": [ "Contacts" ], "operationId": "accept_terms", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactsAccess" } } } }, "403": { "description": "" } } } }, "/v1/contacts/{id}/outcome": { "post": { "tags": [ "Contacts" ], "operationId": "report_outcome", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactOutcomeInput" } } }, "required": true }, "responses": { "202": { "description": "" }, "400": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/people": { "get": { "tags": [ "People" ], "operationId": "list_people", "parameters": [ { "name": "q", "in": "query", "description": "Name, or part of one.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "within_days", "in": "query", "description": "Only people named on a filing published in the last N days.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "state", "in": "query", "description": "Two-letter US state.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonPage" } } } }, "400": { "description": "" }, "401": { "description": "" }, "429": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/people/{id}": { "get": { "tags": [ "People" ], "operationId": "get_person", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "401": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/people/{id}/contact-search": { "post": { "tags": [ "Contacts" ], "operationId": "find_contact_details", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearch" } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactSearch" } } } }, "403": { "description": "" }, "404": { "description": "" }, "429": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/people/{id}/contacts": { "get": { "tags": [ "Contacts" ], "operationId": "person_contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonContacts" } } } }, "403": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/public/signals/sample": { "get": { "tags": [ "Signals" ], "summary": "The landing page's \"This morning's events\": five rows, no officers, no details, no auth.", "operationId": "public_sample", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } } } } } }, "/v1/public/status": { "get": { "tags": [ "Signals" ], "operationId": "public_status", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStatus" } } } } } } }, "/v1/public/your-details": { "get": { "tags": [ "Your details" ], "operationId": "your_details", "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YourDetails" } } } }, "404": { "description": "" } } } }, "/v1/public/your-details/link": { "post": { "tags": [ "Your details" ], "operationId": "send_link", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailsLinkInput" } } }, "required": true }, "responses": { "202": { "description": "" }, "400": { "description": "" }, "429": { "description": "" } } } }, "/v1/public/your-details/remove": { "post": { "tags": [ "Your details" ], "operationId": "remove", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemovalInput" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/YourDetails" } } } }, "400": { "description": "" }, "404": { "description": "" } } } }, "/v1/saved-searches": { "get": { "tags": [ "Saved searches" ], "operationId": "list", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SavedSearch" } } } } }, "401": { "description": "" } } }, "post": { "tags": [ "Saved searches" ], "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchInput" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "" }, "401": { "description": "" } } } }, "/v1/saved-searches/{id}": { "delete": { "tags": [ "Saved searches" ], "operationId": "remove", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "" }, "404": { "description": "" } } }, "patch": { "tags": [ "Saved searches" ], "operationId": "update", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearchPatch" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "404": { "description": "" } } } }, "/v1/signal-types": { "get": { "tags": [ "Signals" ], "operationId": "list_signal_types", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SignalTypeInfo" } } } } } } } }, "/v1/signals": { "get": { "tags": [ "Signals" ], "operationId": "search_signals", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "since", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "country", "in": "query", "description": "US or GB (UK is accepted).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "state", "in": "query", "description": "US state or UK region.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "industry", "in": "query", "description": "Matches the industry group or a SIC code prefix.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "min_amount", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "max_amount", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "stage", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Full text over company names, places and officer names.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "exclude_funds", "in": "query", "description": "Leave out investment funds and SPVs (they file Form D too). Default false.", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "within_days", "in": "query", "description": "Only signals published in the last N days. Saved searches use this so they stay relative.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalPage" } } } }, "400": { "description": "" }, "401": { "description": "" }, "403": { "description": "" }, "429": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/signals/export": { "get": { "tags": [ "Signals" ], "operationId": "export_signals", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "since", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "country", "in": "query", "description": "US or GB (UK is accepted).", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "state", "in": "query", "description": "US state or UK region.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "industry", "in": "query", "description": "Matches the industry group or a SIC code prefix.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "min_amount", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "max_amount", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "stage", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Full text over company names, places and officer names.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "exclude_funds", "in": "query", "description": "Leave out investment funds and SPVs (they file Form D too). Default false.", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "within_days", "in": "query", "description": "Only signals published in the last N days. Saved searches use this so they stay relative.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "text/csv": {} } }, "400": { "description": "" }, "401": { "description": "" }, "429": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/signals/feed": { "get": { "tags": [ "Signals" ], "operationId": "signals_feed", "parameters": [ { "name": "cursor", "in": "query", "description": "From a previous page's `next_cursor`; omit to start from the beginning.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedPage" } } } }, "400": { "description": "" }, "401": { "description": "" }, "429": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/usage": { "get": { "tags": [ "Account" ], "operationId": "usage", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "list_webhooks", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } }, "security": [ { "bearer": [] } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "create_webhook", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } }, "required": true }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "" } }, "security": [ { "bearer": [] } ] } }, "/v1/webhooks/{id}": { "delete": { "tags": [ "Webhooks" ], "operationId": "delete_webhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "" }, "404": { "description": "" } }, "security": [ { "bearer": [] } ] } } }, "components": { "schemas": { "Company": { "type": "object", "required": [ "id", "name", "country", "sic_codes", "registry_id", "first_seen_at", "officers", "signals" ], "properties": { "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "contacts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ContactPoint" }, "description": "Present only for callers with the `daybreak.contacts` scope and entitlement." }, "country": { "type": "string" }, "entity_type": { "type": [ "string", "null" ] }, "first_seen_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "incorporated_on": { "type": [ "string", "null" ], "format": "date" }, "industry": { "type": [ "string", "null" ] }, "jurisdiction": { "type": [ "string", "null" ] }, "latest_stage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Stage" } ] }, "name": { "type": "string" }, "officers": { "type": "array", "items": { "$ref": "#/components/schemas/Officer" } }, "phone": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "registry_id": { "type": "string", "description": "SEC CIK or Companies House number." }, "sic_codes": { "type": "array", "items": { "type": "string" } }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" }, "description": "Every signal about the company, newest first." }, "total_raised_usd": { "type": [ "integer", "null" ], "format": "int64" }, "website": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompanyWebsite", "description": "The company's website, once someone has asked for it." } ] }, "year_incorporated": { "type": [ "integer", "null" ], "format": "int32" } } }, "CompanyWebsite": { "type": "object", "description": "A company's website as we found and checked it.", "required": [ "status" ], "properties": { "confidence": { "type": [ "number", "null" ], "format": "float", "description": "0 to 1. Found is 0.8 or more; likely is 0.5 to 0.8." }, "domain": { "type": [ "string", "null" ] }, "links": { "$ref": "#/components/schemas/WebsiteLinks" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "What matched, in words: \"the filed phone number is on the homepage\"." }, "retry_after": { "type": [ "string", "null" ], "format": "date-time", "description": "A miss can be searched again after this." }, "searched_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "description": "searching | found | likely | none | failed" }, "url": { "type": [ "string", "null" ] } } }, "ContactOutcomeInput": { "type": "object", "description": "What happened when the customer used an address.", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "description": "hard_bounce | complaint | unsubscribed | wrong_person | left_company" } } }, "ContactPoint": { "type": "object", "description": "A work email or phone for a person at the company. Empty until contacts are switched on.", "required": [ "person", "kind", "value", "status", "provider", "checked_at" ], "properties": { "checked_at": { "type": "string", "format": "date-time" }, "domain": { "type": [ "string", "null" ], "description": "The company website the address was found on." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": [ "string", "null" ], "format": "uuid" }, "kind": { "type": "string", "description": "email | phone" }, "notice": { "type": [ "string", "null" ], "description": "none | due | sent | delivered | bounced: whether the person has been told we hold it." }, "person": { "type": "string" }, "person_id": { "type": [ "string", "null" ] }, "provenance": { "type": "array", "items": { "type": "object" }, "description": "Where each part came from: the filing, the website evidence, the provider." }, "provider": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "role_address": { "type": "boolean", "description": "info@, hello@ and the like: the company's, not the person's." }, "sender_rule": { "type": [ "string", "null" ], "description": "The rule the sender must keep, e.g. \"us_can_spam\"." }, "status": { "type": "string", "description": "verified | valid | catch_all | unknown | invalid | stale" }, "value": { "type": "string" } } }, "ContactSearch": { "type": "object", "description": "One contact search for one person, shared by every account that asks.", "required": [ "id", "person_id", "status", "created_at" ], "properties": { "answered_from_cache": { "type": "boolean", "description": "This ask was answered from an earlier search." }, "contact": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContactPoint", "description": "The address, once found and the person has been told." } ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "description": "`cs_…`" }, "person_id": { "type": "string" }, "reason": { "type": [ "string", "null" ], "description": "Why it ended without an address: no_website, suppressed, entity, fund, …" }, "retry_after": { "type": [ "string", "null" ], "format": "date-time", "description": "A miss can be searched again after this." }, "status": { "type": "string", "description": "queued | searching | found | guess | not_found | skipped | failed | deferred" }, "step": { "type": [ "string", "null" ], "description": "While searching: website | email | verify | notice" } } }, "ContactSearchLog": { "type": "object", "required": [ "data", "stats" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactSearchLogEntry" } }, "stats": { "$ref": "#/components/schemas/ContactSearchStats" } } }, "ContactSearchLogEntry": { "type": "object", "description": "One ask, in the account's search log.", "required": [ "asked_at", "person_id", "person_name", "company_id", "company_name", "channel", "status", "answered_from_cache" ], "properties": { "answered_from_cache": { "type": "boolean" }, "asked_at": { "type": "string", "format": "date-time" }, "channel": { "type": "string", "description": "web | api | mcp" }, "company_id": { "type": "string", "format": "uuid" }, "company_name": { "type": "string" }, "person_id": { "type": "string" }, "person_name": { "type": "string" }, "status": { "type": "string" }, "value": { "type": [ "string", "null" ] } } }, "ContactSearchStats": { "type": "object", "description": "This month's asks, for the Contacts page.", "required": [ "asked", "found", "guesses", "not_found", "reused" ], "properties": { "asked": { "type": "integer", "format": "int64" }, "found": { "type": "integer", "format": "int64" }, "guesses": { "type": "integer", "format": "int64" }, "not_found": { "type": "integer", "format": "int64" }, "reused": { "type": "integer", "format": "int64" } } }, "ContactsAccess": { "type": "object", "description": "The account's contacts switch, and what the button has left today.", "required": [ "enabled", "daily_limit", "searches_today", "current_terms_version" ], "properties": { "current_terms_version": { "type": "string", "description": "The version the account must accept now." }, "daily_limit": { "type": "integer", "format": "int32" }, "enabled": { "type": "boolean" }, "enabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "searches_today": { "type": "integer", "format": "int64" }, "terms_accepted_at": { "type": [ "string", "null" ], "format": "date-time" }, "terms_version": { "type": [ "string", "null" ] } } }, "DetailsLinkInput": { "type": "object", "description": "\"Send me a link\" from the public page.", "required": [ "email" ], "properties": { "email": { "type": "string" } } }, "FeedPage": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": "string", "description": "Pass back as `cursor`. Present on the last page too, so a client can poll for newer events." } } }, "InferredStage": { "type": "object", "description": "A round stage worked out from the filing, never stated by it.", "required": [ "stage", "confidence", "method" ], "properties": { "confidence": { "type": "string", "description": "low | medium | high" }, "method": { "type": "string", "description": "The rule that produced it, in words." }, "stage": { "$ref": "#/components/schemas/Stage" } } }, "Officer": { "type": "object", "required": [ "name", "source_signal_id" ], "properties": { "is_entity": { "type": "boolean", "description": "A promoter or manager filed as a company, not a person: never searched for contacts." }, "name": { "type": "string" }, "person_id": { "type": [ "string", "null" ], "description": "The person page for this officer (`per_…`)." }, "role": { "type": [ "string", "null" ] }, "source_signal_id": { "type": "string", "description": "The signal (filing) that named this person." } } }, "Person": { "type": "object", "description": "A person named on filings. People are one name on one company for now: the same name at two\ncompanies is two people until cross-company matching exists.", "required": [ "id", "name", "country", "is_entity", "removed", "roles" ], "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "id": { "type": "string", "description": "`per_…`, stable." }, "is_entity": { "type": "boolean" }, "name": { "type": "string", "description": "\"Removed at their request\" when the person opted out." }, "region": { "type": [ "string", "null" ] }, "removed": { "type": "boolean", "description": "The person asked to be removed: name withheld, no contact search." }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/PersonRole" } } } }, "PersonCompany": { "type": "object", "description": "The company a person is named at.", "required": [ "id", "name", "country" ], "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ] } } }, "PersonContacts": { "type": "object", "description": "What the person panel shows: the latest search this account asked for, and its addresses.", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactPoint" } }, "search": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ContactSearch" } ] } } }, "PersonPage": { "type": "object", "required": [ "data", "page", "per_page", "total", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonSummary" } }, "has_more": { "type": "boolean" }, "page": { "type": "integer", "format": "int32", "minimum": 0 }, "per_page": { "type": "integer", "format": "int32", "minimum": 0 }, "total": { "type": "integer", "format": "int64" } } }, "PersonRole": { "type": "object", "description": "One role on one filing.", "required": [ "company", "source" ], "properties": { "company": { "$ref": "#/components/schemas/PersonCompany" }, "source": { "$ref": "#/components/schemas/RoleSource" }, "title": { "type": [ "string", "null" ], "description": "As filed, e.g. \"Executive Officer, Director (CEO)\"." } } }, "PersonSummary": { "type": "object", "description": "A row in the people list.", "required": [ "id", "name", "company", "filed_on" ], "properties": { "amount_usd": { "type": [ "integer", "null" ], "format": "int64", "description": "Amount sold on the latest funding filing that named them." }, "city": { "type": [ "string", "null" ] }, "company": { "$ref": "#/components/schemas/PersonCompany" }, "filed_on": { "type": "string", "format": "date" }, "id": { "type": "string" }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } }, "PublicStatus": { "type": "object", "description": "`GET /v1/public/status`: how fresh the data is, for the landing page and the search header.", "required": [ "new_signals", "signal_counts" ], "properties": { "latest_published": { "type": [ "string", "null" ], "format": "date", "description": "The newest publication date on file." }, "new_signals": { "type": "integer", "format": "int64", "description": "Signals published on `latest_published`." }, "signal_counts": { "type": "array", "items": { "$ref": "#/components/schemas/SignalCount" }, "description": "All-time count per signal type." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the last successful ingest run finished." } } }, "RemovalInput": { "type": "object", "description": "\"Remove me\" or \"remove only my email\", from the public page.", "required": [ "scope" ], "properties": { "scope": { "type": "string", "description": "person | email" } } }, "RoleSource": { "type": "object", "description": "Where a person's role comes from.", "required": [ "kind", "reference", "url", "filed_on" ], "properties": { "filed_on": { "type": "string", "format": "date" }, "kind": { "type": "string", "description": "`sec_form_d`" }, "reference": { "type": "string", "description": "The filing's accession number." }, "url": { "type": "string" } } }, "SavedSearch": { "type": "object", "description": "A query the account keeps and comes back to, with what arrived since it was last opened.", "required": [ "id", "name", "query", "morning_email", "created_at", "last_opened_at", "companies", "signals", "new_signals" ], "properties": { "companies": { "type": "integer", "format": "int64", "description": "Across the whole query, now." }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "last_opened_at": { "type": "string", "format": "date-time" }, "morning_email": { "type": "boolean", "description": "Email the creator each morning when something new matches." }, "name": { "type": "string" }, "new_signals": { "type": "integer", "format": "int64", "description": "Signals that arrived after `last_opened_at`." }, "query": { "type": "string", "description": "The `/v1/signals` query string, without paging, e.g. `type=funding.filed&country=US&within_days=7`." }, "signals": { "type": "integer", "format": "int64" } } }, "SavedSearchInput": { "type": "object", "required": [ "name", "query" ], "properties": { "morning_email": { "type": "boolean" }, "name": { "type": "string" }, "query": { "type": "string" } } }, "SavedSearchPatch": { "type": "object", "description": "Rename, switch the morning email, or mark as opened (resets what counts as new).", "properties": { "morning_email": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "opened": { "type": "boolean" } } }, "Signal": { "type": "object", "required": [ "id", "type", "company", "published_on", "ingested_at", "evidence_url", "details" ], "properties": { "amount_usd": { "type": [ "integer", "null" ], "format": "int64", "description": "Form D: total amount sold so far, in USD." }, "company": { "$ref": "#/components/schemas/SignalCompany" }, "details": { "type": "object", "description": "Source-specific facts (offering amount, investors, securities, officer role…)." }, "evidence_url": { "type": "string", "description": "The official filing this signal came from." }, "id": { "type": "string", "description": "Deterministic: `sec:`, `ch::incorporated`, `sec::officer:`." }, "inferred_stage": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/InferredStage" } ] }, "ingested_at": { "type": "string", "format": "date-time" }, "occurred_on": { "type": [ "string", "null" ], "format": "date", "description": "When it happened (Form D: date of first sale; Companies House: incorporation date)." }, "published_on": { "type": "string", "format": "date", "description": "When the source published it (the filing date)." }, "supersedes": { "type": [ "string", "null" ], "description": "For `funding.amended`: the signal it updates." }, "type": { "$ref": "#/components/schemas/SignalType" } } }, "SignalCompany": { "type": "object", "required": [ "id", "name", "country" ], "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "description": "ISO 3166 alpha-2: US or GB." }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "region": { "type": [ "string", "null" ] } } }, "SignalCount": { "type": "object", "required": [ "name", "count" ], "properties": { "count": { "type": "integer", "format": "int64" }, "name": { "type": "string" } } }, "SignalPage": { "type": "object", "required": [ "data", "page", "per_page", "total", "has_more" ], "properties": { "companies": { "type": "integer", "format": "int64", "description": "Distinct companies across every page of the result." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } }, "first_published": { "type": [ "string", "null" ], "format": "date", "description": "The oldest and newest publication dates across the result." }, "funds_hidden": { "type": "integer", "format": "int64", "description": "Fund and SPV signals the query matched but left out because of `exclude_funds`." }, "has_more": { "type": "boolean" }, "last_published": { "type": [ "string", "null" ], "format": "date" }, "page": { "type": "integer", "format": "int32", "minimum": 0 }, "per_page": { "type": "integer", "format": "int32", "minimum": 0 }, "total": { "type": "integer", "format": "int64" } } }, "SignalType": { "type": "string", "enum": [ "company.incorporated", "funding.filed", "funding.amended", "officer.listed" ] }, "SignalTypeInfo": { "type": "object", "required": [ "name", "label", "description", "source" ], "properties": { "description": { "type": "string" }, "label": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" } } }, "Stage": { "type": "string", "enum": [ "pre_seed", "seed", "series_a", "later" ] }, "UsageRow": { "type": "object", "required": [ "key_name", "rest", "mcp", "feed" ], "properties": { "api_key_id": { "type": [ "string", "null" ], "format": "uuid" }, "feed": { "type": "integer", "format": "int64" }, "key_name": { "type": "string" }, "mcp": { "type": "integer", "format": "int64" }, "rest": { "type": "integer", "format": "int64" } } }, "UsageSummary": { "type": "object", "required": [ "month", "quota", "used", "rows" ], "properties": { "month": { "type": "string" }, "quota": { "type": "integer", "format": "int64" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/UsageRow" } }, "used": { "type": "integer", "format": "int64" } } }, "Webhook": { "type": "object", "required": [ "id", "url", "events", "active", "created_at" ], "properties": { "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string", "format": "uuid" }, "secret": { "type": [ "string", "null" ], "description": "Shown once, when the webhook is created: signs every delivery (HMAC-SHA256)." }, "url": { "type": "string" } } }, "WebhookInput": { "type": "object", "description": "A webhook subscription.", "required": [ "url", "events" ], "properties": { "events": { "type": "array", "items": { "type": "string" }, "description": "contact_search.completed | person.removed | website.found" }, "url": { "type": "string" } } }, "WebsiteCorrectionInput": { "type": "object", "description": "A proposed correction to a company's website.", "properties": { "domain": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] } } }, "WebsiteLinks": { "type": "object", "description": "Links taken from the company's own homepage.", "properties": { "linkedin": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "x": { "type": [ "string", "null" ] } } }, "YourDetails": { "type": "object", "description": "The public \"your details\" page: what we hold about one person.", "required": [ "name", "roles", "filings", "emails", "customers_shown", "removed" ], "properties": { "customers_shown": { "type": "integer", "format": "int64", "description": "How many business customers were shown an address." }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/YourDetailsEmail" } }, "filings": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "removed": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } } } }, "YourDetailsEmail": { "type": "object", "required": [ "value", "found_on", "provider" ], "properties": { "delete_by": { "type": [ "string", "null" ], "format": "date-time" }, "found_on": { "type": "string", "format": "date-time" }, "provider": { "type": "string" }, "value": { "type": "string" } } } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_..." } } }, "tags": [ { "name": "Signals" }, { "name": "Companies" }, { "name": "People" }, { "name": "Contacts" }, { "name": "Webhooks" }, { "name": "Your details" }, { "name": "Account" }, { "name": "Saved searches" } ] }