{ "openapi": "3.1.0", "info": { "title": "Signalbase API", "description": "Complete Signalbase V2 API: signal endpoints (funding, acquisitions, job changes, hiring, investors), companies, people, CSV enrichment, and webhooks. Generated from the per-page specs under api-reference/*/openapi.json (run scripts/build-openapi.mjs).", "version": "2.3.0" }, "servers": [ { "url": "https://www.trysignalbase.com/api/v2" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/signals/funding": { "get": { "summary": "Get Funding Signals", "description": "Fetch funding signals with filtering, pagination, and search capabilities. Returns a list of companies with funding activity including round types, amounts, and investor information.", "operationId": "getFundingSignals", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "dateFrom", "in": "query", "description": "Filter signals from this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "dateTo", "in": "query", "description": "Filter signals up to this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-12-31" }, { "name": "date_preset", "in": "query", "description": "Relative date shorthand. Takes precedence over dateFrom/dateTo when provided.", "schema": { "type": "string", "enum": [ "today", "yesterday", "last_7d", "last_14d", "last_30d", "last_60d", "last_90d", "last_6m", "last_1y", "last_2y", "this_week", "this_month", "this_quarter", "this_year", "last_week", "last_month", "last_quarter", "last_year" ] }, "example": "last_30d" }, { "name": "countries", "in": "query", "description": "Comma-separated list of country codes to filter by", "schema": { "type": "string" }, "example": "US,GB,CA" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country names or codes to EXCLUDE (denylist), e.g. `China` or `CN`. Complements `countries`. Companies with an unknown/NULL HQ country are kept, not excluded.", "schema": { "type": "string" }, "example": "CN" }, { "name": "categories", "in": "query", "description": "Pipe-separated list of company categories / industries to filter by", "schema": { "type": "string" }, "example": "Technology|Healthcare" }, { "name": "round", "in": "query", "description": "Comma-separated list of funding round types to filter by. Exact, case-insensitive match ('Series A', 'series a', and 'SERIES A' all match). A value not in the accepted list returns 400 Bad Request. See the Enums page for the accepted values.", "schema": { "type": "string" }, "example": "Seed,Series A" }, { "name": "round_flavor", "in": "query", "description": "Comma-separated list of round flavors to filter by", "schema": { "type": "string", "enum": [ "bridge", "extension", "secondary" ] }, "example": "bridge" }, { "name": "subcategories", "in": "query", "description": "Comma-separated list of subcategory IDs to filter by. These filter companies based on their assigned subcategory.", "schema": { "type": "string", "enum": [ "ai", "saas", "software", "cybersecurity", "web3", "devtools", "analytics", "cloud", "iot", "fintech", "payments", "accounting", "ecommerce", "insurance", "vc & investment", "regtech", "marketing", "advertising", "sales", "hr tech", "legal", "healthcare", "biotechnology", "education", "real estate", "energy", "logistics", "manufacturing", "retail", "agriculture", "food & beverage", "automotive", "aerospace & defense", "robotics", "telecommunications", "travel", "sports", "gaming", "media", "govtech", "construction", "environmental services", "battery technology", "arts", "architecture", "cosmetics", "science", "non-profit" ] }, "example": "ai,fintech" }, { "name": "search", "in": "query", "description": "Search by company name or industry keywords", "schema": { "type": "string" }, "example": "fintech" }, { "name": "industry", "in": "query", "description": "Comma-separated list of exact industry names to filter by", "schema": { "type": "string" }, "example": "Financial Services,Healthcare" }, { "name": "company_name", "in": "query", "description": "Search by company name (partial match)", "schema": { "type": "string" }, "example": "stripe" }, { "name": "company_domain", "in": "query", "description": "**Recommended.** Company website domain, e.g. `novartis.com`. Strict match — if no company has this domain the result is empty; never falls back to fuzzy name matching. Variants are equivalent: `novartis.com`, `www.novartis.com` and `https://novartis.com/` all match the same company. Malformed values return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "novartis.com" }, { "name": "company_linkedin_url", "in": "query", "description": "**Recommended.** LinkedIn company URL, e.g. `linkedin.com/company/novartis`. Strict match — if no company has this LinkedIn page the result is empty; never falls back to fuzzy name matching. `http`/`https`, optional `www.` and trailing slash are equivalent. Non-company LinkedIn URLs (e.g. personal `/in/` profiles) return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "linkedin.com/company/novartis" }, { "name": "amount_min", "in": "query", "description": "Minimum funding amount in whole units of the deal's currency (not cents)", "schema": { "type": "integer" }, "example": 1000000 }, { "name": "amount_max", "in": "query", "description": "Maximum funding amount in whole units of the deal's currency (not cents)", "schema": { "type": "integer" }, "example": 50000000 }, { "name": "currency", "in": "query", "description": "Filter by currency, as an ISO 4217 code (e.g. USD, EUR, GBP). Most records are USD. Exact match.", "schema": { "type": "string", "enum": [ "USD", "EUR", "GBP", "CHF", "JPY", "INR", "CAD", "AUD", "SEK", "CNY", "NZD", "KRW", "SGD", "DKK", "BRL" ] }, "example": "USD" }, { "name": "verification_status", "in": "query", "description": "Comma-separated list of verification statuses to filter by", "schema": { "type": "string", "enum": [ "verified", "unverified", "pending" ] }, "example": "verified" }, { "name": "investor_name", "in": "query", "description": "Search by investor name (partial match)", "schema": { "type": "string" }, "example": "Sequoia" }, { "name": "employee_count_min", "in": "query", "description": "Minimum company employee count", "schema": { "type": "integer" }, "example": 10 }, { "name": "employee_count_max", "in": "query", "description": "Maximum company employee count", "schema": { "type": "integer" }, "example": 500 }, { "name": "founded_year_min", "in": "query", "description": "Minimum company founded year", "schema": { "type": "integer" }, "example": 2020 }, { "name": "founded_year_max", "in": "query", "description": "Maximum company founded year", "schema": { "type": "integer" }, "example": 2025 }, { "name": "sort_by", "in": "query", "description": "Field to sort results by", "schema": { "type": "string", "enum": [ "occurred_at", "discovered_at", "amount", "employee_count", "founded_year" ], "default": "occurred_at" }, "example": "occurred_at" }, { "name": "sort_order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc" }, { "name": "count", "in": "query", "description": "When set to \"true\", returns only pagination metadata (totalCount) with an empty data array. No credits are charged.", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Successful response with funding signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_FundingSignalsResponse" }, "example": { "success": true, "data": [ { "signalId": "f9422f20-bcdc-4d38-8049-4cda561bc9dd", "signalType": "funding_round", "match_confidence": "exact", "occurredAt": "2026-03-17T04:05:52.903Z", "discoveredAt": "2026-03-17T05:06:08.184Z", "companyId": "3bba1b2e-fb85-485e-80d5-5cc4617cfe13", "companyName": "dtcpay", "companySlug": "dtcpay", "companyLogo": "https://images.trysignalbase.com/dtcpay.png", "companyWebsite": "dtcpay.com", "companyLinkedin": "linkedin.com/company/digital-treasures-center-pte-ltd", "companyIndustry": "Financial Services", "companyCountry": "SG", "companySubcategory": "fintech", "companyFoundedYear": 2019, "companyCategories": "[\"Financial Services\",\"Payments\"]", "companyDescription": "dtcpay is a regulated payment service provider enabling seamless digital payments.", "companyEmployeeCount": 125, "roundType": "series a", "roundFlavor": null, "amount": 10000000, "currency": "USD", "announcedDate": "2026-03-17", "confidenceScore": 0.95, "verificationStatus": "verified", "isFreeAccess": true, "investors": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Sequoia Capital", "type": "vc", "website": "https://www.sequoiacap.com", "linkedin": "linkedin.com/company/sequoia-capital", "isLead": true }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Andreessen Horowitz", "type": "vc", "website": "https://a16z.com", "linkedin": "linkedin.com/company/a16z", "isLead": false } ], "sources": [ { "url": "https://technode.global/2026/03/17/dtcpay-raises-10m-series-a", "sourceType": "news_article", "title": "dtcpay raises $10M in Series A led by Sequoia Capital", "publishedAt": "2026-03-17T04:05:52.903Z", "isPrimary": true } ] } ], "pagination": { "currentPage": 1, "totalPages": 15, "totalCount": 300, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "signals.funding", "creditsUsed": 1, "creditsRemaining": 999 } } } } }, "400": { "description": "Bad request - an invalid filter value was supplied (e.g. an unrecognized `round` value)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ErrorResponse" }, "example": { "success": false, "error": "Invalid round value: foobar. Accepted values (case-insensitive): pre-seed, seed, series a, series b, series c, series d, series e, series f, series g, series h, angel, grant, crowdfunding, growth, debt, debt financing, equity, fund, ipo." } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Funding_ErrorResponse" }, "example": { "success": false, "error": "An unknown error occurred" } } } } } } }, "/signals/acquisitions": { "get": { "summary": "Get Acquisition Signals", "description": "Fetch acquisition signals with filtering, pagination, and search capabilities. Returns acquisition events with acquired company details, acquiring company information, deal amounts, and source references.", "operationId": "getAcquisitionSignals", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "dateFrom", "in": "query", "description": "Filter signals from this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "dateTo", "in": "query", "description": "Filter signals up to this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-12-31" }, { "name": "date_preset", "in": "query", "description": "Relative date shorthand. Takes precedence over dateFrom/dateTo.", "schema": { "type": "string", "enum": [ "today", "yesterday", "last_7d", "last_14d", "last_30d", "last_60d", "last_90d", "last_6m", "last_1y", "last_2y", "this_week", "this_month", "this_quarter", "this_year", "last_week", "last_month", "last_quarter", "last_year" ] }, "example": "last_90d" }, { "name": "countries", "in": "query", "description": "Comma-separated list of country codes to filter by (acquired company)", "schema": { "type": "string" }, "example": "US,GB" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country names or codes to EXCLUDE for the ACQUIRED company's HQ (denylist), e.g. `China` or `CN`. Complements `countries`. Deals whose acquired company has an unknown/NULL HQ are kept.", "schema": { "type": "string" }, "example": "CN" }, { "name": "categories", "in": "query", "description": "Pipe-separated list of company categories / industries to filter by", "schema": { "type": "string" }, "example": "Technology|Healthcare" }, { "name": "subcategories", "in": "query", "description": "Comma-separated list of subcategory IDs to filter by", "schema": { "type": "string" }, "example": "ai,fintech" }, { "name": "search", "in": "query", "description": "Search by company name or industry keywords", "schema": { "type": "string" }, "example": "tech" }, { "name": "industry", "in": "query", "description": "Comma-separated list of exact industry names to filter by", "schema": { "type": "string" }, "example": "Financial Services" }, { "name": "company_name", "in": "query", "description": "Search by acquired company name (partial match)", "schema": { "type": "string" }, "example": "stripe" }, { "name": "company_domain", "in": "query", "description": "**Recommended.** Company website domain, e.g. `novartis.com`. Strict match — if no company has this domain the result is empty; never falls back to fuzzy name matching. Variants are equivalent: `novartis.com`, `www.novartis.com` and `https://novartis.com/` all match the same company. Malformed values return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "novartis.com" }, { "name": "company_linkedin_url", "in": "query", "description": "**Recommended.** LinkedIn company URL, e.g. `linkedin.com/company/novartis`. Strict match — if no company has this LinkedIn page the result is empty; never falls back to fuzzy name matching. `http`/`https`, optional `www.` and trailing slash are equivalent. Non-company LinkedIn URLs (e.g. personal `/in/` profiles) return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "linkedin.com/company/novartis" }, { "name": "acquiring_company", "in": "query", "description": "Search by acquiring company name (partial match)", "schema": { "type": "string" }, "example": "Google" }, { "name": "acquirer_countries", "in": "query", "description": "Comma-separated list of country codes for the ACQUIRING company's HQ (allowlist). Independent of `countries`/`exclude_countries`, which target the acquired company.", "schema": { "type": "string" }, "example": "US,GB" }, { "name": "exclude_acquirer_countries", "in": "query", "description": "Comma-separated list of country names or codes to EXCLUDE for the ACQUIRING company's HQ (denylist), e.g. `China` or `CN`. Deals with an unknown/NULL acquirer HQ are kept.", "schema": { "type": "string" }, "example": "CN" }, { "name": "amount_min", "in": "query", "description": "Minimum acquisition amount in whole USD (not cents)", "schema": { "type": "integer" }, "example": 10000000 }, { "name": "amount_max", "in": "query", "description": "Maximum acquisition amount in whole USD (not cents)", "schema": { "type": "integer" }, "example": 1000000000 }, { "name": "currency", "in": "query", "description": "Filter by currency, as an ISO 4217 code. Acquisition amounts are stored as USD by convention (the vast majority); a few records are EUR. Exact match.", "schema": { "type": "string", "enum": [ "USD", "EUR" ] }, "example": "USD" }, { "name": "verification_status", "in": "query", "description": "Comma-separated list of verification statuses to filter by", "schema": { "type": "string", "enum": [ "verified", "unverified", "pending" ] }, "example": "verified" }, { "name": "employee_count_min", "in": "query", "description": "Minimum company employee count", "schema": { "type": "integer" }, "example": 10 }, { "name": "employee_count_max", "in": "query", "description": "Maximum company employee count", "schema": { "type": "integer" }, "example": 500 }, { "name": "founded_year_min", "in": "query", "description": "Minimum company founded year", "schema": { "type": "integer" }, "example": 2015 }, { "name": "founded_year_max", "in": "query", "description": "Maximum company founded year", "schema": { "type": "integer" }, "example": 2025 }, { "name": "sort_by", "in": "query", "description": "Field to sort results by", "schema": { "type": "string", "enum": [ "occurred_at", "discovered_at", "amount", "employee_count" ], "default": "occurred_at" }, "example": "occurred_at" }, { "name": "sort_order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc" }, { "name": "count", "in": "query", "description": "When set to \"true\", returns only pagination metadata with an empty data array. No credits are charged.", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Successful response with acquisition signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Acquisition_AcquisitionSignalsResponse" }, "example": { "success": true, "data": [ { "signalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "signalType": "acquisition", "match_confidence": "exact", "occurredAt": "2026-02-10T12:00:00.000Z", "discoveredAt": "2026-02-10T14:30:00.000Z", "companyId": "d4e5f6a7-b8c9-0123-defg-h45678901234", "companyName": "DataVault", "companySlug": "datavault", "companyLogo": "https://images.trysignalbase.com/datavault.png", "companyWebsite": "datavault.io", "companyLinkedin": "linkedin.com/company/datavault", "companyIndustry": "Data Analytics", "companyCountry": "US", "companySubcategory": "saas", "companyFoundedYear": 2019, "companyCategories": "[\"Data Analytics\",\"SaaS\"]", "companyDescription": "Enterprise data analytics platform.", "companyEmployeeCount": 85, "acquiringCompanyId": "e5f6a7b8-c9d0-1234-efgh-i56789012345", "amount": 250000000, "currency": "USD", "percentage": "100%", "announcedDate": "2026-02-10", "isFreeAccess": true, "acquiringCompany": { "id": "e5f6a7b8-c9d0-1234-efgh-i56789012345", "name": "Snowflake", "slug": "snowflake", "logo": "https://images.trysignalbase.com/snowflake.png", "website": "snowflake.com", "linkedin": "linkedin.com/company/snowflake", "industry": "Cloud Computing", "companyCountry": "US", "companySubcategory": "cloud", "foundedYear": 2012, "employeeCount": 5000 }, "sources": [ { "url": "https://techcrunch.com/2026/02/10/snowflake-acquires-datavault", "sourceType": "news_article", "title": "Snowflake acquires DataVault for $250M", "publishedAt": "2026-02-10T12:00:00.000Z", "isPrimary": true } ] } ], "pagination": { "currentPage": 1, "totalPages": 25, "totalCount": 500, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "signals.acquisitions", "creditsUsed": 1, "creditsRemaining": 999 } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Acquisition_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Acquisition_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Acquisition_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Acquisition_ErrorResponse" }, "example": { "success": false, "error": "An unknown error occurred" } } } } } } }, "/signals/job-changes": { "get": { "summary": "Get Job Change Signals", "description": "Fetch job change signals with filtering, pagination, and search. Supports role-aware position filters, department and seniority filters, LinkedIn targeting, and field-specific search. Person names are GDPR-masked (first name + last initial only).", "operationId": "getJobChangeSignals", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "dateFrom", "in": "query", "description": "Filter signals from this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "dateTo", "in": "query", "description": "Filter signals up to this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-12-31" }, { "name": "date_preset", "in": "query", "description": "Relative date shorthand. Takes precedence over dateFrom/dateTo.", "schema": { "type": "string", "enum": [ "today", "yesterday", "last_7d", "last_14d", "last_30d", "last_60d", "last_90d", "last_6m", "last_1y", "last_2y", "this_week", "this_month", "this_quarter", "this_year", "last_week", "last_month", "last_quarter", "last_year" ] }, "example": "last_30d" }, { "name": "search", "in": "query", "description": "Free-text search across company name, industry, person name, role, person location, and person country", "schema": { "type": "string" }, "example": "engineering leadership" }, { "name": "countries", "in": "query", "description": "Comma-separated list of country codes to filter by (matches person country or company HQ)", "schema": { "type": "string" }, "example": "US,GB" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country names or codes to EXCLUDE (denylist), e.g. `China`. A signal is excluded when EITHER the person country or the company HQ matches; rows with a NULL field on a side are kept.", "schema": { "type": "string" }, "example": "CN" }, { "name": "city", "in": "query", "description": "Free-text search on person city and person location", "schema": { "type": "string" }, "example": "San Francisco" }, { "name": "personLinkedinUrl", "in": "query", "description": "Exact LinkedIn profile URL of the person", "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/example" }, { "name": "company_linkedin_url", "in": "query", "description": "**Recommended.** LinkedIn company URL, e.g. `linkedin.com/company/novartis`. Strict match — if no company has this LinkedIn page the result is empty; never falls back to fuzzy name matching. `http`/`https`, optional `www.` and trailing slash are equivalent. Non-company LinkedIn URLs (e.g. personal `/in/` profiles) return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty. (Legacy alias: `companyLinkedinUrl`.)", "schema": { "type": "string" }, "example": "linkedin.com/company/novartis" }, { "name": "company_name", "in": "query", "description": "Search by company name (partial match)", "schema": { "type": "string" }, "example": "Google" }, { "name": "company_domain", "in": "query", "description": "**Recommended.** Company website domain, e.g. `novartis.com`. Strict match — if no company has this domain the result is empty; never falls back to fuzzy name matching. Variants are equivalent: `novartis.com`, `www.novartis.com` and `https://novartis.com/` all match the same company. Malformed values return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "novartis.com" }, { "name": "new_role", "in": "query", "description": "Search by new role / job title (partial match)", "schema": { "type": "string" }, "example": "VP Engineering" }, { "name": "source", "in": "query", "description": "Exact match on signal source", "schema": { "type": "string", "enum": [ "linkedin", "press_release", "other" ] }, "example": "linkedin" }, { "name": "keyword", "in": "query", "description": "Search by keyword tag (partial match)", "schema": { "type": "string" }, "example": "promotion" }, { "name": "positions", "in": "query", "description": "Comma-separated list of positions to filter by (e.g., ceo, cto, cfo, coo, vp of engineering, head of product, engineering manager, product manager, founder, co-founder)", "schema": { "type": "string" }, "example": "cto,head of engineering" }, { "name": "departments", "in": "query", "description": "Comma-separated list of departments to filter by (e.g., marketing, sales, engineering, product, design, operations, finance, people, data, customer_success, growth, legal)", "schema": { "type": "string" }, "example": "engineering,product" }, { "name": "seniorities", "in": "query", "description": "Comma-separated list of seniority levels to filter by (e.g., founder, c_level, vp, director, head, lead, manager)", "schema": { "type": "string" }, "example": "c_level,vp,head" }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "occurred_at", "discovered_at", "person_name", "company_name" ], "default": "occurred_at" }, "example": "occurred_at" }, { "name": "sort_order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc" }, { "name": "count", "in": "query", "description": "When set to \"true\", returns only pagination metadata with an empty data array. No credits are charged.", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Successful response with job change signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChange_JobChangeSignalsResponse" }, "example": { "success": true, "data": [ { "signalId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "signalType": "job_change", "match_confidence": "exact", "occurredAt": "2026-03-01T00:00:00.000Z", "discoveredAt": "2026-03-02T12:00:00.000Z", "personName": "Alex J.", "personLinkedinUrl": "https://www.linkedin.com/in/alexjohnson", "companyLinkedinUrl": "https://www.linkedin.com/company/nextgensoftware", "newRole": "Chief Technology Officer", "postContent": "Excited to announce my new role as CTO at NextGen Software!", "takenFrom": "https://www.linkedin.com/feed/update/urn:li:activity:123456", "source": "linkedin", "companyName": "NextGen Software", "personCurrentTitle": "Chief Technology Officer at NextGen Software", "personHeadline": "CTO | Building the future of enterprise software", "personLocation": "San Francisco Bay Area", "personCity": "San Francisco", "personCountry": "US", "personFollowers": 5200, "personConnections": 2500, "personPosts": null, "companyWebsite": "https://www.nextgensoftware.com", "companyIndustry": "Technology", "companyCountry": "US", "companySubcategory": "saas", "companyEmployeeCount": 250, "companyFoundedYear": 2018, "companyLogoUrl": "https://images.trysignalbase.com/nextgen.png", "companyDescription": "Enterprise software company.", "companySpecialties": "[\"Cloud\",\"SaaS\"]", "companyCategories": "[\"Technology\",\"Software\"]", "isFreeAccess": true, "companyLogo": "https://images.trysignalbase.com/nextgen.png", "sources": [ { "url": "https://www.linkedin.com/feed/update/urn:li:activity:123456", "sourceType": "social_media" } ] } ], "pagination": { "currentPage": 1, "totalPages": 12, "totalCount": 240, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "signals.jobChanges", "creditsUsed": 1, "creditsRemaining": 999 } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChange_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChange_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChange_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobChange_ErrorResponse" }, "example": { "success": false, "error": "An unknown error occurred" } } } } } } }, "/signals/hiring": { "get": { "summary": "Get Hiring Signals", "description": "Fetch hiring signals (open job postings) with filtering, pagination, and search. Supports role-aware position filters, department and seniority filters, location targeting, team size, and applicant range filtering.", "operationId": "getHiringSignals", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "dateFrom", "in": "query", "description": "Filter signals from this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "dateTo", "in": "query", "description": "Filter signals up to this date (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-12-31" }, { "name": "date_preset", "in": "query", "description": "Relative date shorthand. Takes precedence over dateFrom/dateTo.", "schema": { "type": "string", "enum": [ "today", "yesterday", "last_7d", "last_14d", "last_30d", "last_60d", "last_90d", "last_6m", "last_1y", "last_2y", "this_week", "this_month", "this_quarter", "this_year", "last_week", "last_month", "last_quarter", "last_year" ] }, "example": "last_30d" }, { "name": "search", "in": "query", "description": "Free-text search across company name, industry, job title, location, and city", "schema": { "type": "string" }, "example": "engineering" }, { "name": "description", "in": "query", "description": "Full-text keyword search over the job description body only. Opt-in and separate from `search` — use it to find postings mentioning specific keywords, skills, or tools. Matches whole words (not substrings) and supports websearch-style syntax: space-separated terms are ANDed, \"quoted phrases\" match in order, and OR / leading - (exclude) are honored (e.g. `kubernetes OR terraform -intern`).", "schema": { "type": "string" }, "example": "Kubernetes" }, { "name": "countries", "in": "query", "description": "Comma-separated list of country codes to filter by. Matches the job listing country OR the company HQ country. To match the job location only, use job_countries instead.", "schema": { "type": "string" }, "example": "US,GB,DE" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country names or codes to EXCLUDE (denylist), e.g. `China`. A signal is excluded when EITHER the job-listing country or the company HQ matches; rows with a NULL field on a side are kept.", "schema": { "type": "string" }, "example": "CN" }, { "name": "company_countries", "in": "query", "description": "Comma-separated country codes matching the company HQ country ONLY (ignores job listing location). The HQ-only counterpart of job_countries; use countries to match either side. The three country scopes AND together if combined, so pick one.", "schema": { "type": "string" }, "example": "GB" }, { "name": "job_countries", "in": "query", "description": "Comma-separated country codes matching the job listing location ONLY (ignores company HQ). Use this to filter by where the job is, not where the company is based. Note: countries and job_countries are ANDed if both are supplied, so use one or the other, not both.", "schema": { "type": "string" }, "example": "US,GB" }, { "name": "states", "in": "query", "description": "Comma-separated US state codes to filter by", "schema": { "type": "string" }, "example": "CA,NY,TX" }, { "name": "city", "in": "query", "description": "Free-text search on hiring signal city, location, and region", "schema": { "type": "string" }, "example": "San Francisco" }, { "name": "categories", "in": "query", "description": "Pipe-separated list of company industry categories to filter by", "schema": { "type": "string" }, "example": "Technology|Software" }, { "name": "subcategories", "in": "query", "description": "Comma-separated list of subcategory IDs to filter by", "schema": { "type": "string" }, "example": "ai,fintech,saas" }, { "name": "positions", "in": "query", "description": "Comma-separated list of positions to filter by (e.g., ceo, cto, cfo, coo, vp of engineering, head of product, engineering manager, product manager, founder, co-founder)", "schema": { "type": "string" }, "example": "cto,head of engineering" }, { "name": "departments", "in": "query", "description": "Comma-separated list of departments to filter by (e.g., marketing, sales, engineering, product, design, operations, finance, people, data, customer_success, growth, legal)", "schema": { "type": "string" }, "example": "engineering,product" }, { "name": "seniorities", "in": "query", "description": "Comma-separated list of seniority levels to filter by (e.g., founder, c_level, vp, director, head, lead, manager)", "schema": { "type": "string" }, "example": "c_level,vp,head" }, { "name": "team_size", "in": "query", "description": "Comma-separated team size ranges (e.g., 1-10, 11-50, 51-200, 201-1000, 1000-plus)", "schema": { "type": "string" }, "example": "51-200,201-1000" }, { "name": "applicants", "in": "query", "description": "Comma-separated applicant count ranges (e.g., 0-25, 26-50, 51-100, 101-200, 201-plus)", "schema": { "type": "string" }, "example": "0-25,26-50" }, { "name": "company_name", "in": "query", "description": "Search by company name (partial match, fuzzy). Prefer `company_domain` or `company_linkedin_url` for strict matching.", "schema": { "type": "string" }, "example": "stripe" }, { "name": "company_domain", "in": "query", "description": "**Recommended.** Company website domain, e.g. `novartis.com`. Strict match — if no company has this domain the result is empty; never falls back to fuzzy name matching. Variants are equivalent: `novartis.com`, `www.novartis.com` and `https://novartis.com/` all match the same company. Malformed values return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "novartis.com" }, { "name": "company_linkedin_url", "in": "query", "description": "**Recommended.** LinkedIn company URL, e.g. `linkedin.com/company/novartis`. Strict match — if no company has this LinkedIn page the result is empty; never falls back to fuzzy name matching. `http`/`https`, optional `www.` and trailing slash are equivalent. Non-company LinkedIn URLs (e.g. personal `/in/` profiles) return 400. Takes priority over `company_name`; combined identifiers must agree or the result is empty.", "schema": { "type": "string" }, "example": "linkedin.com/company/novartis" }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "date_posted", "created_at", "title", "company_name", "location" ], "default": "created_at" }, "example": "date_posted" }, { "name": "sort_order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc" }, { "name": "count", "in": "query", "description": "When set to \"true\", returns only pagination metadata with an empty data array. No credits are charged.", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Successful response with hiring signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hiring_HiringSignalsResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "match_confidence": "exact", "jobId": "123456789", "jobUrl": "https://www.linkedin.com/jobs/view/123456789", "title": "Senior Software Engineer", "location": "San Francisco, CA", "city": "San Francisco", "region": "California", "jobCountry": "US", "datePosted": "2026-03-01T00:00:00.000Z", "validThrough": "2026-05-01T00:00:00.000Z", "employmentType": "Full-time", "seniorityLevel": "Mid-Senior level", "jobFunction": "Engineering", "industries": "Software Development", "numApplicants": "45", "descriptionText": "We are looking for a senior software engineer...", "createdAt": "2026-03-02T12:00:00.000Z", "companyId": "d4e5f6a7-b8c9-0123-defg-h45678901234", "companyName": "NextGen Software", "companyWebsite": "https://www.nextgensoftware.com", "companyIndustry": "Technology", "companyCountry": "US", "companySubcategory": "saas", "companyEmployeeCount": 250, "companyFoundedYear": 2018, "companyLogoUrl": "https://images.trysignalbase.com/nextgen.png", "companyDescription": "Enterprise software company.", "companySpecialties": "[\"Cloud\",\"SaaS\"]", "companyCategories": "[\"Technology\",\"Software\"]", "isFreeAccess": true, "companyLogo": "https://images.trysignalbase.com/nextgen.png" } ], "pagination": { "currentPage": 1, "totalPages": 50, "totalCount": 1000, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "signals.hiring", "creditsUsed": 1, "creditsRemaining": 999 } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hiring_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hiring_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hiring_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Hiring_ErrorResponse" }, "example": { "success": false, "error": "An unknown error occurred" } } } } } } }, "/signals/investors": { "get": { "summary": "Get Investor Data", "description": "Fetch investor data with filtering, pagination, and search. Returns venture capital firms, angel investors, PE firms, corporate investors, accelerators, family offices, hedge funds, and crowdfunding platforms.", "operationId": "getInvestors", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "dateFrom", "in": "query", "description": "Filter by created date from (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-01-01" }, { "name": "dateTo", "in": "query", "description": "Filter by created date to (ISO 8601 format: YYYY-MM-DD)", "schema": { "type": "string", "format": "date" }, "example": "2024-12-31" }, { "name": "date_preset", "in": "query", "description": "Relative date shorthand. Takes precedence over dateFrom/dateTo.", "schema": { "type": "string", "enum": [ "today", "yesterday", "last_7d", "last_14d", "last_30d", "last_60d", "last_90d", "last_6m", "last_1y", "last_2y", "this_week", "this_month", "this_quarter", "this_year", "last_week", "last_month", "last_quarter", "last_year" ] }, "example": "last_1y" }, { "name": "search", "in": "query", "description": "Free-text search across investor name and type", "schema": { "type": "string" }, "example": "sequoia" }, { "name": "countries", "in": "query", "description": "Comma-separated list of country codes to filter by (matches investor's countries JSON array)", "schema": { "type": "string" }, "example": "US,GB" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country codes to EXCLUDE (denylist), e.g. `CN`. Investors with no listed countries are kept, not excluded.", "schema": { "type": "string" }, "example": "CN" }, { "name": "type", "in": "query", "description": "Comma-separated list of investor types to filter by. The underlying `type` data is free-text, so these values are convenience groupings matched case-insensitively against many real-world variants (e.g. `vc` matches \"VC\", \"VC firm\", \"Venture Capital\", \"venture_capital\", \"Corporate VC\"; `angel` matches \"Angel\", \"Solo angel\", \"Angel network\"). For anything outside this list, use the `search` parameter, which also matches the type field. Note: the `type` value in the response is the original scraped string (e.g. \"Corporate VC\"), not the slug you filtered by, so a single `type=vc` query returns rows with mixed `type` values.", "schema": { "type": "string", "enum": [ "vc", "angel", "pe", "corporate", "government", "accelerator", "family_office", "hedge_fund", "crowdfunding" ] }, "example": "vc,angel" }, { "name": "categories", "in": "query", "description": "Legacy: Pipe-separated list of investor types (same as type parameter)", "schema": { "type": "string" }, "example": "vc|angel" }, { "name": "headquarters", "in": "query", "description": "Search by headquarters location (partial match)", "schema": { "type": "string" }, "example": "San Francisco" }, { "name": "ticket_size_min", "in": "query", "description": "Minimum ticket size in USD", "schema": { "type": "integer" }, "example": 100000 }, { "name": "ticket_size_max", "in": "query", "description": "Maximum ticket size in USD", "schema": { "type": "integer" }, "example": 5000000 }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "name", "created_at", "ticket_size_min", "ticket_size_max" ], "default": "created_at" }, "example": "name" }, { "name": "sort_order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "asc" }, { "name": "count", "in": "query", "description": "When set to \"true\", returns only pagination metadata with an empty data array. No credits are charged.", "schema": { "type": "string", "enum": [ "true" ] } } ], "responses": { "200": { "description": "Successful response with investor data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investors_InvestorsResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Sequoia Capital", "type": "vc", "linkedinUrl": "linkedin.com/company/sequoia-capital", "website": "https://www.sequoiacap.com", "logoUrl": "https://images.trysignalbase.com/sequoia.png", "countries": "[\"US\",\"IN\",\"CN\"]", "ticketSizeMin": 1000000, "ticketSizeMax": 100000000, "headquarters": "Menlo Park, California", "createdAt": "2025-01-15T10:00:00.000Z", "isFreeAccess": true }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Y Combinator", "type": "accelerator", "linkedinUrl": "linkedin.com/company/y-combinator", "website": "https://www.ycombinator.com", "logoUrl": "https://images.trysignalbase.com/ycombinator.png", "countries": "[\"US\"]", "ticketSizeMin": 125000, "ticketSizeMax": 500000, "headquarters": "Mountain View, California", "createdAt": "2025-01-10T08:00:00.000Z", "isFreeAccess": true } ], "pagination": { "currentPage": 1, "totalPages": 50, "totalCount": 1000, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "signals.investors", "creditsUsed": 1, "creditsRemaining": 999 } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investors_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investors_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investors_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Investors_ErrorResponse" }, "example": { "success": false, "error": "An unknown error occurred" } } } } } } }, "/companies": { "get": { "summary": "Get Companies", "description": "Browse and search companies with filtering, pagination, and sorting. Returns company profiles with industry, headcount, location, and metadata — independent of any signal data.", "operationId": "getCompanies", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "example": 20 }, { "name": "search", "in": "query", "description": "Free-text search across company name, industry, description, keywords, and specialties", "schema": { "type": "string" }, "example": "AI" }, { "name": "domain", "in": "query", "description": "Resolve a specific company by its website domain (exact match, not fuzzy). Accepted URL variants — scheme, `www.`, port, path and trailing slash — are normalized. Invalid syntax returns 400; a valid domain with no match returns an empty data set. ANDed with any other filters.", "schema": { "type": "string" }, "example": "novartis.com" }, { "name": "linkedin_url", "in": "query", "description": "Resolve a specific company by its LinkedIn URL (exact match, not fuzzy). Scheme, `www.` and a trailing slash are normalized. Invalid syntax returns 400; a valid URL with no match returns an empty data set. ANDed with any other filters.", "schema": { "type": "string" }, "example": "https://www.linkedin.com/company/novartis" }, { "name": "countries", "in": "query", "description": "Comma-separated list of country codes to filter by", "schema": { "type": "string" }, "example": "US,GB,DE" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country names or codes to EXCLUDE (denylist), e.g. `China` or `CN`. Complements `countries`. Companies with an unknown/NULL HQ country are kept, not excluded.", "schema": { "type": "string" }, "example": "CN" }, { "name": "industry", "in": "query", "description": "Comma-separated list of industry names to filter by (exact match)", "schema": { "type": "string" }, "example": "Software,Technology" }, { "name": "categories", "in": "query", "description": "Pipe-separated list of company industry categories to filter by", "schema": { "type": "string" }, "example": "Technology|Software" }, { "name": "subcategories", "in": "query", "description": "Comma-separated list of subcategory IDs to filter by", "schema": { "type": "string" }, "example": "ai,fintech,saas" }, { "name": "employee_count_min", "in": "query", "description": "Minimum employee count", "schema": { "type": "integer", "minimum": 0 }, "example": 50 }, { "name": "employee_count_max", "in": "query", "description": "Maximum employee count", "schema": { "type": "integer", "minimum": 0 }, "example": 5000 }, { "name": "founded_year_min", "in": "query", "description": "Minimum founded year", "schema": { "type": "integer", "minimum": 1800 }, "example": 2020 }, { "name": "founded_year_max", "in": "query", "description": "Maximum founded year", "schema": { "type": "integer", "minimum": 1800 }, "example": 2025 }, { "name": "sort_by", "in": "query", "description": "Field to sort by", "schema": { "type": "string", "enum": [ "name", "employee_count", "founded_year", "created_at" ], "default": "name" }, "example": "employee_count" }, { "name": "sort_order", "in": "query", "description": "Sort direction", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "example": "desc" }, { "name": "count", "in": "query", "description": "If set to true, returns only the total count without data rows and without deducting credits.", "schema": { "type": "string", "enum": [ "true" ] }, "example": "true" } ], "responses": { "200": { "description": "Successful response with companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies_CompaniesResponse" }, "example": { "success": true, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "NextGen Software", "slug": "nextgen-software", "description": "Enterprise SaaS platform for workflow automation.", "website": "https://www.nextgensoftware.com", "linkedinUrl": "https://www.linkedin.com/company/nextgensoftware", "twitterUrl": "https://twitter.com/nextgensoftware", "logoUrl": "https://media.licdn.com/dms/image/example.png", "industry": "Technology", "foundedYear": 2018, "headquartersCountry": "US", "employeeCount": 250, "categories": [ "Software", "SaaS", "Enterprise" ], "keywords": [ "workflow automation", "enterprise", "AI" ], "specialties": [ "process automation", "integration" ], "growthInfo": { "growth_1m": 1.2, "growth_3m": 3.5, "growth_6m": 8.1, "growth_9m": 12, "growth_12m": 18.5 }, "createdAt": "2024-06-15T10:30:00Z", "updatedAt": "2024-11-20T14:00:00Z" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "HealthTech Solutions", "slug": "healthtech-solutions", "description": "AI-powered healthcare diagnostics platform for early disease detection.", "website": "https://www.healthtechsolutions.co.uk", "linkedinUrl": "https://www.linkedin.com/company/healthtechsolutions", "twitterUrl": null, "logoUrl": "https://media.licdn.com/dms/image/example2.png", "industry": "Healthcare Technology", "foundedYear": 2022, "headquartersCountry": "GB", "employeeCount": 85, "categories": [ "Healthcare", "AI" ], "keywords": [ "diagnostics", "AI", "health" ], "specialties": [ "disease detection", "medical imaging" ], "growthInfo": null, "createdAt": "2024-08-01T09:00:00Z", "updatedAt": "2024-11-18T11:30:00Z" } ], "pagination": { "currentPage": 1, "totalPages": 200, "totalCount": 4000, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "companies.list", "creditsUsed": 1, "creditsRemaining": 4999 } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Companies_ErrorResponse" }, "example": { "success": false, "error": "An unknown error occurred" } } } } } } }, "/people": { "get": { "summary": "Search People", "description": "Discover people across employees and job-change subjects, filtered by title, function, seniority, geography, company attributes, and signal activity. Each result includes an inline `matched_signal` — the latest signal that matched your filters — plus `is_latest_signal`, which reports whether that matched signal is also the person's newest overall signal.\n\nDifferent filters combine with AND; comma-separated values within a single filter combine with OR. A person qualifies if any of their signals match the filters, and the latest matching one is surfaced as `matched_signal`. Results are deduplicated by normalized person LinkedIn URL (falling back to normalized name + company identity) before pagination. Default sort is `matched_signal.date` descending.", "operationId": "searchPeople", "parameters": [ { "name": "page", "in": "query", "description": "Page number for pagination", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 }, { "name": "limit", "in": "query", "description": "Number of results per page (maximum 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "example": 100 }, { "name": "title", "in": "query", "description": "Job title or comma-separated list (e.g. `CTO,VP of Engineering`). Matched with word boundaries via taxonomy/pattern logic — `COO` will not match `Cook` or `Coordinator`, and `Assistant to the CEO` is excluded from `CEO`.", "schema": { "type": "string" }, "example": "CTO,VP of Engineering" }, { "name": "function", "in": "query", "description": "Comma-separated function ids. Accepted values: `marketing`, `sales`, `engineering`, `product`, `design`, `operations`, `finance`, `people`, `data`, `customer_success`, `growth`, `legal`. Unknown values return 400.", "schema": { "type": "string" }, "example": "engineering,product" }, { "name": "seniority", "in": "query", "description": "Comma-separated seniority ids. Accepted values: `founder`, `c_level`, `vp`, `director`, `head`, `lead`, `manager`. Unknown values return 400.", "schema": { "type": "string" }, "example": "c_level,vp" }, { "name": "country", "in": "query", "description": "ISO 3166-1 alpha-2 country code or comma-separated list (e.g. `US,NL`). Matches either the company's country or the person's country.", "schema": { "type": "string" }, "example": "US,NL" }, { "name": "person_countries", "in": "query", "description": "ISO 3166-1 alpha-2 country code or comma-separated list (e.g. `GB,IE`). Matches the person's own country only — no company-country fallback, unlike `country`. Person location is currently available on a minority of records (job-change sourced), so this filter favors precision over recall; combine with `country` if you need maximum coverage.", "schema": { "type": "string" }, "example": "GB,IE" }, { "name": "exclude_countries", "in": "query", "description": "Comma-separated list of country codes to EXCLUDE (denylist), e.g. `CN`. A person is excluded when EITHER their company country or their own person country matches; rows with an unknown country on a side are kept.", "schema": { "type": "string" }, "example": "CN" }, { "name": "city", "in": "query", "description": "Free-text city match (partial, case-insensitive). Only job-change people carry city data today; employee-sourced people have no city and are excluded when this filter is set.", "schema": { "type": "string" }, "example": "Amsterdam" }, { "name": "company_size", "in": "query", "description": "Comma-separated company size bands, matched against the company's employee count. Accepted values: `1-10`, `11-50`, `51-100`, `101-250`, `251-500`, `501-1000`, `1000-plus`. People whose record has no linked company with a known headcount are excluded when this filter is set. Unknown values return 400.", "schema": { "type": "string" }, "example": "51-100,101-250" }, { "name": "industry", "in": "query", "description": "Industry name or comma-separated list (case-insensitive exact match on the company's industry).", "schema": { "type": "string" }, "example": "SaaS,Fintech" }, { "name": "linkedin_url", "in": "query", "description": "Person LinkedIn profile URL — resolves a specific person instead of browsing an ICP. Matches current employees and job-change subjects by canonical equality; scheme, `www.` and a trailing slash are accepted and ignored. Must be a personal profile URL (`/in/` or legacy `/pub/`) — pass a company page to `company_linkedin_url` instead. Invalid syntax returns 400; a valid URL with no match returns an empty data set. When set, `signal_date_range` defaults to all-time.", "schema": { "type": "string" }, "example": "https://www.linkedin.com/in/jane-doe" }, { "name": "company_domain", "in": "query", "description": "Company website domain — returns the people at that company. Exact (canonicalized) match; scheme, `www.`, port, path and trailing slash are normalized. Invalid syntax returns 400; no match returns an empty data set. When set, `signal_date_range` defaults to all-time.", "schema": { "type": "string" }, "example": "novartis.com" }, { "name": "company_linkedin_url", "in": "query", "description": "Company LinkedIn URL — returns the people at that company. Exact (canonicalized) match; scheme, `www.` and trailing slash are normalized. Invalid syntax returns 400; no match returns an empty data set. When set, `signal_date_range` defaults to all-time.", "schema": { "type": "string" }, "example": "https://www.linkedin.com/company/novartis" }, { "name": "signal_type", "in": "query", "description": "Comma-separated signal type(s) to pin `matched_signal` to. Accepted values: `funding_round`, `acquisition`, `job_change`. When omitted, `matched_signal` is the person's newest qualifying signal of any supported type, so types can mix across a page. Unknown values return 400.", "schema": { "type": "string" }, "example": "funding_round" }, { "name": "signal_date_range", "in": "query", "description": "Lookback window for the matched signal, as `` where unit is `d` (days), `w` (weeks), `m` (months), or `y` (years) — e.g. `30d`, `6m`, `12m`, `2y`. People whose latest matching signal falls outside this window are excluded. Malformed or out-of-range values return 400. Default: `12m` for a normal ICP browse, but all-time when an identifier lookup (`linkedin_url`, `company_domain`, or `company_linkedin_url`) is set — pass an explicit value to still narrow the window.", "schema": { "type": "string", "default": "12m" }, "example": "6m" }, { "name": "include_former", "in": "query", "description": "Whether to include former employees. Currently only `false` is supported — passing `true` returns 400 because job-change records have no current/former semantics yet. The endpoint is active-only (current employees).", "schema": { "type": "string", "enum": [ "false" ], "default": "false" }, "example": "false" }, { "name": "count", "in": "query", "description": "If set to `true`, returns only the total count without data rows and without deducting credits.", "schema": { "type": "string", "enum": [ "true" ] }, "example": "true" } ], "responses": { "200": { "description": "Successful response with people", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/People_PeopleResponse" }, "example": { "success": true, "data": [ { "name": "Sarah K.", "linkedin_url": "https://www.linkedin.com/in/sarah-k", "title": "Chief Technology Officer", "status": "active", "city": null, "country": null, "company": { "name": "NextGen Software", "domain": "nextgensoftware.com", "linkedin_url": "https://www.linkedin.com/company/nextgensoftware", "country": "NL", "city": null, "size_band": "101-250", "industry": "Technology" }, "is_latest_signal": true, "matched_signal": { "type": "funding_round", "date": "2026-05-12", "summary": "Series B, $40M led by Accel", "source_url": "https://techcrunch.com/2026/05/12/nextgen-series-b" } }, { "name": "Michael R.", "linkedin_url": "https://www.linkedin.com/in/michael-r", "title": "VP of Engineering", "status": "active", "city": "Berlin", "country": "DE", "company": { "name": "HealthTech Solutions", "domain": "healthtechsolutions.co.uk", "linkedin_url": "https://www.linkedin.com/company/healthtechsolutions", "country": "GB", "city": null, "size_band": "51-100", "industry": "Healthcare Technology" }, "is_latest_signal": false, "matched_signal": { "type": "job_change", "date": "2026-04-02", "summary": "Michael R. started as VP of Engineering at HealthTech Solutions", "source_url": "https://www.linkedin.com/in/michael-r" } } ], "pagination": { "currentPage": 1, "totalPages": 12, "totalCount": 1183, "hasNextPage": true, "hasPreviousPage": false }, "meta": { "endpoint": "people.list", "creditsUsed": 1, "creditsRemaining": 4999 } } } } }, "400": { "description": "Bad request - invalid filter value (e.g. unknown function/seniority/company_size/signal_type, malformed signal_date_range, or include_former=true)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/People_ErrorResponse" }, "example": { "success": false, "error": "Invalid seniority value: exec. Accepted values: founder, c_level, vp, director, head, lead, manager." } } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/People_ErrorResponse" }, "example": { "success": false, "error": "Invalid API key" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/People_ErrorResponse" }, "example": { "success": false, "error": "out of credits, please contact support to increase your usage" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/People_ErrorResponse" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later." } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/People_ErrorResponse" }, "example": { "success": false, "error": "Failed to search people" } } } } } } }, "/csv-enrichment": { "post": { "summary": "Create CSV Enrichment Job", "description": "Submit companies for enrichment. Each company must include at least one identifier: company name, website URL/domain, or LinkedIn URL. The endpoint costs 1 credit per accepted job. Add wait=true for small lists to return completed results inline when processing finishes within timeout seconds.", "operationId": "createCSVEnrichmentJob", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Csv_CSVEnrichmentRequest" }, "example": { "fileName": "target-accounts.csv", "wait": true, "timeout": 30, "companies": [ { "company_name": "Mollie", "website_url": "mollie.com", "external_id": "acct_123" } ] } } } }, "responses": { "200": { "description": "Enrichment job accepted. If wait=true and processing completed, data also includes status, summary, and results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Csv_CSVEnrichmentCreateResponse" }, "examples": { "accepted": { "summary": "Asynchronous job accepted", "value": { "success": true, "data": { "jobId": "7f4b7a34-8d65-4cc3-8ab0-3477f8a967a6", "detectedMapping": { "companyName": "company_name", "websiteUrl": "website_url", "linkedinUrl": "linkedin_url" } }, "meta": { "endpoint": "csv.enrichment", "creditsUsed": 1, "creditsRemaining": 999 } } }, "waitCompleted": { "summary": "wait=true completed within timeout", "value": { "success": true, "data": { "jobId": "7f4b7a34-8d65-4cc3-8ab0-3477f8a967a6", "detectedMapping": { "companyName": "company_name", "websiteUrl": "website_url", "linkedinUrl": null }, "status": "completed", "progress": { "processed": 1, "total": 1 }, "submittedAt": "2026-05-12T07:25:42.000Z", "completedAt": "2026-05-12T07:26:01.000Z", "summary": { "totalInputs": 1, "matched": 1, "unmatched": 0, "withFundingSignals": 0, "withAcquisitionSignals": 0, "withHiringSignals": 1, "withJobChangeSignals": 0 }, "results": [ { "input": { "company_name": "Mollie", "website_url": "mollie.com" }, "matched": true, "companyId": "c5ff2e53-0c99-4b6a-964e-63c2fc7e2a8e", "company": { "name": "Mollie", "domain": "mollie.com", "industry": "Financial Services", "country": "NL", "employeeCount": 850 }, "signals": { "funding": [], "acquisition": [], "hiring": [], "job_change": [], "investors": [] } } ], "nextCursor": null }, "meta": { "endpoint": "csv.enrichment", "creditsUsed": 1, "creditsRemaining": 999 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/InsufficientCredits" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/csv-enrichment/{jobId}": { "get": { "summary": "Get CSV Enrichment Job", "description": "Retrieve job status, progress, summary counts, and completed results. Polling is free and returns creditsUsed: 0. Results are paginated with cursor and limit.", "operationId": "getCSVEnrichmentJob", "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "Job ID returned by POST /csv-enrichment", "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "description": "Pagination cursor returned as data.nextCursor", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page. Defaults to 50, maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Job status and results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Csv_CSVEnrichmentGetResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/JobNotFound" }, "410": { "$ref": "#/components/responses/JobExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks": { "post": { "summary": "Create Webhook", "description": "Create a webhook subscription for the authenticated team. The full signing secret is returned exactly once in this response — store it now, because every later read returns only a 4-character preview. Creating a webhook is free (0 API credits). A team may have at most 10 active webhooks.", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookCreateRequest" }, "example": { "endpoint_url": "https://example.com/hooks/signalbase", "event_types": [ "funding.created", "hiring.created" ], "filters": { "countries": "US,GB" } } } } }, "responses": { "201": { "description": "Webhook created. data includes the full signing secret (shown only on create).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookCreateResponse" }, "example": { "success": true, "data": { "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "endpoint_url": "https://example.com/hooks/signalbase", "event_types": [ "funding.created", "hiring.created" ], "filters": { "countries": "US,GB" }, "active": true, "created_at": "2026-05-29T10:30:00.000Z", "updated_at": "2026-05-29T10:30:00.000Z", "last_modified_by": "user_2a9f8c7b6d5e4f3a", "last_modified_via": "api", "secret": "3f9a1c7e-2b4d-4e6a-9f1b-8c2d3e4f5a6b", "stats": { "total_deliveries": 0, "successful_deliveries": 0, "failed_deliveries": 0, "last_success_at": null, "last_failure_at": null, "consecutive_failures": 0 } }, "meta": { "endpoint": "webhooks.create", "creditsUsed": 0 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "summary": "List Webhooks", "description": "List the authenticated team's active webhook subscriptions, newest first. Secrets are never returned here — each item includes only secret_preview. Free (0 credits).", "operationId": "listWebhooks", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of webhooks to return. Minimum 1, maximum 100, default 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Number of webhooks to skip for pagination. Default 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Array of webhook subscriptions (secret preview only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookListResponse" }, "example": { "success": true, "data": [ { "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "endpoint_url": "https://example.com/hooks/signalbase", "event_types": [ "funding.created", "hiring.created" ], "filters": { "countries": "US,GB" }, "active": true, "created_at": "2026-05-29T10:30:00.000Z", "updated_at": "2026-05-29T10:30:00.000Z", "last_modified_by": "user_2a9f8c7b6d5e4f3a", "last_modified_via": "api", "secret_preview": "…5a6b", "stats": { "total_deliveries": 42, "successful_deliveries": 40, "failed_deliveries": 2, "last_success_at": "2026-05-29T12:00:00.000Z", "last_failure_at": "2026-05-28T09:00:00.000Z", "consecutive_failures": 0 } } ], "pagination": { "limit": 100, "offset": 0, "count": 1 }, "meta": { "endpoint": "webhooks.list", "creditsUsed": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}": { "get": { "summary": "Retrieve Webhook", "description": "Retrieve a single active webhook by ID. Returns secret_preview only (never the full secret). Soft-deleted webhooks return 404. Free (0 credits).", "operationId": "getWebhook", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "The webhook subscription (secret preview only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookGetResponse" }, "example": { "success": true, "data": { "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "endpoint_url": "https://example.com/hooks/signalbase", "event_types": [ "funding.created", "hiring.created" ], "filters": { "countries": "US,GB" }, "active": true, "created_at": "2026-05-29T10:30:00.000Z", "updated_at": "2026-05-29T10:30:00.000Z", "last_modified_by": "user_2a9f8c7b6d5e4f3a", "last_modified_via": "api", "secret_preview": "…5a6b", "stats": { "total_deliveries": 42, "successful_deliveries": 40, "failed_deliveries": 2, "last_success_at": "2026-05-29T12:00:00.000Z", "last_failure_at": "2026-05-28T09:00:00.000Z", "consecutive_failures": 0 } }, "meta": { "endpoint": "webhooks.get", "creditsUsed": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "summary": "Update Webhook", "description": "Update any subset of a webhook's fields. Set rotate_secret to true to mint a new signing secret — the response then includes the full new secret (shown only on rotation) and the previous secret immediately stops verifying. Set active to true to re-enable a previously deleted webhook. Free (0 credits).", "operationId": "updateWebhook", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookUpdateRequest" }, "examples": { "changeEvents": { "summary": "Change subscribed events and pause", "value": { "event_types": [ "funding.created" ], "active": false } }, "rotateSecret": { "summary": "Rotate the signing secret", "value": { "rotate_secret": true } } } } } }, "responses": { "200": { "description": "The updated webhook. Includes the full secret only when rotate_secret was true; otherwise secret_preview.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookUpdateResponse" }, "examples": { "updated": { "summary": "Fields updated (no rotation)", "value": { "success": true, "data": { "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "endpoint_url": "https://example.com/hooks/signalbase", "event_types": [ "funding.created" ], "filters": { "countries": "US,GB" }, "active": false, "created_at": "2026-05-29T10:30:00.000Z", "updated_at": "2026-05-29T13:00:00.000Z", "last_modified_by": "user_2a9f8c7b6d5e4f3a", "last_modified_via": "api", "secret_preview": "…5a6b", "stats": { "total_deliveries": 42, "successful_deliveries": 40, "failed_deliveries": 2, "last_success_at": "2026-05-29T12:00:00.000Z", "last_failure_at": "2026-05-28T09:00:00.000Z", "consecutive_failures": 0 } }, "meta": { "endpoint": "webhooks.update", "creditsUsed": 0 } } }, "rotated": { "summary": "Secret rotated (full secret returned once)", "value": { "success": true, "data": { "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "endpoint_url": "https://example.com/hooks/signalbase", "event_types": [ "funding.created", "hiring.created" ], "filters": { "countries": "US,GB" }, "active": true, "created_at": "2026-05-29T10:30:00.000Z", "updated_at": "2026-05-29T13:05:00.000Z", "last_modified_by": "user_2a9f8c7b6d5e4f3a", "last_modified_via": "api", "secret": "7d2e9b1a-4c6f-4d8e-9a0b-1c2d3e4f5061", "stats": { "total_deliveries": 42, "successful_deliveries": 40, "failed_deliveries": 2, "last_success_at": "2026-05-29T12:00:00.000Z", "last_failure_at": "2026-05-28T09:00:00.000Z", "consecutive_failures": 0 } }, "meta": { "endpoint": "webhooks.update", "creditsUsed": 0 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "summary": "Delete Webhook", "description": "Soft-delete a webhook by setting active to false. It stops receiving events and disappears from list/retrieve. The record and its delivery history are retained, and it can be re-enabled with PUT active:true. Free (0 credits).", "operationId": "deleteWebhook", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "The webhook was soft-deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookDeleteResponse" }, "example": { "success": true, "data": { "success": true, "id": "b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "active": false }, "meta": { "endpoint": "webhooks.delete", "creditsUsed": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/test": { "post": { "summary": "Send Test Event", "description": "Deliver a signed system.test event to the webhook's endpoint immediately, without waiting for a real signal, and record it as a delivery. The request body is ignored. Returns the delivery outcome. Free (0 credits).", "operationId": "testWebhook", "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "The test event was sent and recorded as a delivery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookTestResponse" }, "example": { "success": true, "data": { "success": true, "delivery_id": "9c8b7a65-4d3e-4f21-8a0b-1c2d3e4f5a60", "event_id": "1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071", "event_type": "system.test", "response_status": 200, "response_body": "ok" }, "meta": { "endpoint": "webhooks.test", "creditsUsed": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/deliveries": { "get": { "summary": "List Deliveries", "description": "List delivery attempts for a webhook, newest first, using keyset (cursor) pagination. Optionally filter by status. Free (0 credits).", "operationId": "listWebhookDeliveries", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "name": "limit", "in": "query", "required": false, "description": "Deliveries per page. Minimum 1, maximum 100, default 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "description": "Filter by delivery status.", "schema": { "$ref": "#/components/schemas/Webhook_DeliveryStatus" } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor returned as pagination.next_cursor. Pass it back to fetch the next page. A null next_cursor means there are no more rows.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of delivery attempts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookDeliveriesResponse" }, "example": { "success": true, "data": [ { "id": "9c8b7a65-4d3e-4f21-8a0b-1c2d3e4f5a60", "event_type": "funding.created", "event_id": "1f2e3d4c-5b6a-4790-8a1b-2c3d4e5f6071", "status": "failed", "response_status": 500, "response_body": "internal error", "attempt_count": 1, "delivered_at": null, "failed_at": "2026-05-29T09:00:00.000Z", "created_at": "2026-05-29T09:00:00.000Z" } ], "pagination": { "next_cursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA1LTI5VDA5OjAwOjAwLjAwMFoiLCJpZCI6IjljOGI3YTY1In0", "limit": 50 }, "meta": { "endpoint": "webhooks.deliveries.list", "creditsUsed": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/webhooks/{id}/deliveries/{deliveryId}/retry": { "post": { "summary": "Retry Delivery", "description": "Replay a failed delivery inline. The retry reuses the original event_id and event_type (so receivers can dedupe) and re-signs the payload with the subscription's current secret. Retrying a delivery that already succeeded returns 409. A successful retry is billed as one delivery (1 credit); a failed retry is free.", "operationId": "retryWebhookDelivery", "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "name": "deliveryId", "in": "path", "required": true, "description": "ID of the delivery to retry (the id field from List Deliveries).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The retry was attempted. success indicates whether the replay reached the endpoint with a 2xx.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook_WebhookRetryResponse" }, "example": { "success": true, "data": { "delivery_id": "0a1b2c3d-4e5f-4061-8273-849506a1b2c3", "previous_delivery_id": "9c8b7a65-4d3e-4f21-8a0b-1c2d3e4f5a60", "status": "done", "response_status": 200, "attempt_count": 2, "success": true }, "meta": { "endpoint": "webhooks.deliveries.retry", "creditsUsed": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/SubscriptionExpired" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Use your `ff_live_…` API key as a Bearer token in the Authorization header." } }, "schemas": { "Funding_FundingSignalsResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful", "example": true }, "data": { "type": "array", "description": "Array of funding signal records", "items": { "$ref": "#/components/schemas/Funding_FundingSignal" } }, "pagination": { "$ref": "#/components/schemas/Funding_Pagination" }, "meta": { "$ref": "#/components/schemas/Funding_Meta" } } }, "Funding_FundingSignal": { "type": "object", "required": [ "signalId", "signalType", "occurredAt", "discoveredAt", "companyName", "roundType" ], "properties": { "signalId": { "type": "string", "format": "uuid", "description": "Unique identifier for the funding signal", "example": "f9422f20-bcdc-4d38-8049-4cda561bc9dd" }, "match_confidence": { "type": "string", "enum": [ "exact", "fuzzy", "none" ], "description": "How this row's company was matched: \"exact\" (via `company_domain` / `company_linkedin_url`), \"fuzzy\" (via `company_name` partial match), or \"none\" (no company identifier in the query)." }, "signalType": { "type": "string", "description": "Type of signal (always \"funding_round\" for this endpoint)", "example": "funding_round" }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the funding event occurred", "example": "2026-03-17T04:05:52.903Z" }, "discoveredAt": { "type": "string", "format": "date-time", "description": "When the signal was discovered by our system", "example": "2026-03-17T05:06:08.184Z" }, "companyId": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "3bba1b2e-fb85-485e-80d5-5cc4617cfe13" }, "companyName": { "type": "string", "description": "Name of the company that received funding", "example": "dtcpay" }, "companySlug": { "type": "string", "description": "URL-friendly slug for the company", "example": "dtcpay" }, "companyLogo": { "type": "string", "format": "uri", "nullable": true, "description": "URL to the company logo image", "example": "https://images.trysignalbase.com/dtcpay.png" }, "companyWebsite": { "type": "string", "nullable": true, "description": "Company website URL", "example": "dtcpay.com" }, "companyLinkedin": { "type": "string", "nullable": true, "description": "LinkedIn company page URL", "example": "linkedin.com/company/digital-treasures-center-pte-ltd" }, "companyIndustry": { "type": "string", "nullable": true, "description": "Industry sector of the company", "example": "Financial Services" }, "companyCountry": { "type": "string", "nullable": true, "description": "Country code where the company is headquartered", "example": "SG" }, "companySubcategory": { "type": "string", "nullable": true, "description": "Assigned company subcategory ID (same vocabulary as the `subcategories` query filter). Null when not classified.", "example": "fintech" }, "companyFoundedYear": { "type": "integer", "nullable": true, "description": "Year the company was founded", "example": 2019 }, "companyCategories": { "type": "string", "nullable": true, "description": "JSON-encoded array of company categories", "example": "[\"Financial Services\",\"Payments\"]" }, "companyDescription": { "type": "string", "nullable": true, "description": "Company description", "example": "dtcpay is a regulated payment service provider enabling seamless digital payments." }, "companyEmployeeCount": { "type": "integer", "nullable": true, "description": "Number of employees", "example": 125 }, "roundType": { "type": "string", "nullable": true, "description": "Funding round type (lowercase). Commonly one of the accepted `round` filter values (see the Enums page), but responses may include other, less common round types.", "example": "series a" }, "roundFlavor": { "type": "string", "nullable": true, "description": "Flavor/variant of the funding round (null for standard rounds)", "enum": [ "bridge", "extension", "secondary" ], "example": null }, "amount": { "type": "integer", "nullable": true, "description": "Funding amount in whole units of the deal's currency (not cents); see the Enums page for currency handling", "example": 10000000 }, "currency": { "type": "string", "description": "ISO 4217 currency code for the funding amount (e.g. USD, EUR)", "example": "USD" }, "announcedDate": { "type": "string", "format": "date", "nullable": true, "description": "Date when the funding was announced (YYYY-MM-DD)", "example": "2026-03-17" }, "confidenceScore": { "type": "number", "format": "double", "nullable": true, "description": "AI confidence score for this signal (0.0 to 1.0)", "minimum": 0, "maximum": 1, "example": 0.95 }, "verificationStatus": { "type": "string", "description": "Verification status of the funding signal", "enum": [ "verified", "unverified", "pending" ], "example": "verified" }, "isFreeAccess": { "type": "boolean", "description": "Whether full data is accessible (always true for authenticated requests)", "example": true }, "investors": { "type": "array", "description": "List of investors participating in this round", "items": { "$ref": "#/components/schemas/Funding_Investor" } }, "sources": { "type": "array", "description": "List of source articles and references for this signal", "items": { "$ref": "#/components/schemas/Funding_Source" } } } }, "Funding_Investor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the investor", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "Name of the investor", "example": "Sequoia Capital" }, "type": { "type": "string", "nullable": true, "description": "Type of investor", "enum": [ "vc", "angel", "pe", "corporate", "government", "accelerator", "family_office", "hedge_fund", "crowdfunding" ], "example": "vc" }, "website": { "type": "string", "nullable": true, "description": "Investor website URL", "example": "https://www.sequoiacap.com" }, "linkedin": { "type": "string", "nullable": true, "description": "Investor LinkedIn URL", "example": "linkedin.com/company/sequoia-capital" }, "isLead": { "type": "boolean", "description": "Whether this investor is the lead investor for this round", "example": true } } }, "Funding_Source": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the source article", "example": "https://technode.global/2026/03/17/dtcpay-raises-10m-series-a" }, "sourceType": { "type": "string", "nullable": true, "description": "Type of source", "enum": [ "press_release", "news_article", "social_media", "blog_post", "sec_filing", "crunchbase", "pitchbook" ], "example": "news_article" }, "title": { "type": "string", "nullable": true, "description": "Title of the source article", "example": "dtcpay raises $10M in Series A led by Sequoia Capital" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the source was published", "example": "2026-03-17T04:05:52.903Z" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary source for the signal", "example": true } } }, "Funding_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "description": "Current page number", "minimum": 1, "example": 1 }, "totalPages": { "type": "integer", "description": "Total number of pages available", "minimum": 0, "example": 15 }, "totalCount": { "type": "integer", "description": "Total number of records matching the query", "minimum": 0, "example": 300 }, "hasNextPage": { "type": "boolean", "description": "Indicates if there is a next page", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Indicates if there is a previous page", "example": false } } }, "Funding_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "description": "The endpoint that was called", "example": "signals.funding" }, "creditsUsed": { "type": "number", "description": "Number of API credits consumed by this request", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "Number of API credits remaining after this request", "example": 999 } } }, "Funding_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful (always false for errors)", "example": false }, "error": { "type": "string", "description": "Error message describing what went wrong", "example": "Invalid API key" } } }, "Acquisition_AcquisitionSignalsResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Acquisition_AcquisitionSignal" } }, "pagination": { "$ref": "#/components/schemas/Acquisition_Pagination" }, "meta": { "$ref": "#/components/schemas/Acquisition_Meta" } } }, "Acquisition_AcquisitionSignal": { "type": "object", "required": [ "signalId", "signalType", "occurredAt", "discoveredAt", "companyName" ], "properties": { "signalId": { "type": "string", "format": "uuid", "description": "Unique identifier for the acquisition signal" }, "signalType": { "type": "string", "description": "Type of signal (always \"acquisition\" for this endpoint)", "example": "acquisition" }, "match_confidence": { "type": "string", "enum": [ "exact", "fuzzy", "none" ], "description": "How this row's company was matched: \"exact\" (via `company_domain` / `company_linkedin_url`), \"fuzzy\" (via `company_name` partial match), or \"none\" (no company identifier in the query)." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the acquisition occurred" }, "discoveredAt": { "type": "string", "format": "date-time", "description": "When the signal was discovered" }, "companyId": { "type": "string", "format": "uuid", "description": "Unique identifier for the acquired company" }, "companyName": { "type": "string", "description": "Name of the acquired company" }, "companySlug": { "type": "string", "description": "URL-friendly slug for the acquired company" }, "companyLogo": { "type": "string", "nullable": true, "description": "URL to the acquired company logo" }, "companyWebsite": { "type": "string", "nullable": true, "description": "Acquired company website" }, "companyLinkedin": { "type": "string", "nullable": true, "description": "Acquired company LinkedIn URL" }, "companyIndustry": { "type": "string", "nullable": true, "description": "Industry of the acquired company" }, "companyCountry": { "type": "string", "nullable": true, "description": "Country code of the acquired company" }, "companySubcategory": { "type": "string", "nullable": true, "description": "Assigned subcategory for the acquired company (same vocabulary as the `subcategories` filter)" }, "companyFoundedYear": { "type": "integer", "nullable": true, "description": "Year the acquired company was founded" }, "companyCategories": { "type": "string", "nullable": true, "description": "JSON-encoded array of company categories" }, "companyDescription": { "type": "string", "nullable": true, "description": "Description of the acquired company" }, "companyEmployeeCount": { "type": "integer", "nullable": true, "description": "Employee count of the acquired company" }, "acquiringCompanyId": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the acquiring company (null if unknown)" }, "amount": { "type": "integer", "nullable": true, "description": "Acquisition amount in whole USD (not cents)" }, "currency": { "type": "string", "description": "Currency of the amount, as an ISO 4217 code. Usually \"USD\"; a few records are \"EUR\".", "example": "USD" }, "percentage": { "type": "string", "nullable": true, "description": "Acquisition percentage (e.g., \"100%\", \"51%\", \"partial\")" }, "announcedDate": { "type": "string", "format": "date", "nullable": true, "description": "Date when the acquisition was announced" }, "isFreeAccess": { "type": "boolean", "description": "Whether full data is accessible (always true for authenticated requests)", "example": true }, "acquiringCompany": { "nullable": true, "description": "Details of the acquiring company (null if unknown)", "$ref": "#/components/schemas/Acquisition_AcquiringCompany" }, "sources": { "type": "array", "description": "Source articles and references for this signal", "items": { "$ref": "#/components/schemas/Acquisition_Source" } } } }, "Acquisition_AcquiringCompany": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier" }, "name": { "type": "string", "description": "Company name" }, "slug": { "type": "string", "description": "URL-friendly slug" }, "logo": { "type": "string", "nullable": true, "description": "Logo URL" }, "website": { "type": "string", "nullable": true, "description": "Website URL" }, "linkedin": { "type": "string", "nullable": true, "description": "LinkedIn URL" }, "industry": { "type": "string", "nullable": true, "description": "Industry" }, "companyCountry": { "type": "string", "nullable": true, "description": "Headquarters country code" }, "companySubcategory": { "type": "string", "nullable": true, "description": "Assigned subcategory (same vocabulary as the `subcategories` filter)" }, "foundedYear": { "type": "integer", "nullable": true, "description": "Founded year" }, "employeeCount": { "type": "integer", "nullable": true, "description": "Employee count" } } }, "Acquisition_Source": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the source article" }, "sourceType": { "type": "string", "nullable": true, "description": "Type of source", "enum": [ "press_release", "news_article", "social_media", "blog_post", "sec_filing", "crunchbase", "pitchbook" ] }, "title": { "type": "string", "nullable": true, "description": "Title of the source article" }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "When the source was published" }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary source" } } }, "Acquisition_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "totalPages": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "Acquisition_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "example": "signals.acquisitions" }, "creditsUsed": { "type": "number", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "Credits remaining after this request" } } }, "Acquisition_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "JobChange_JobChangeSignalsResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/JobChange_JobChangeSignal" } }, "pagination": { "$ref": "#/components/schemas/JobChange_Pagination" }, "meta": { "$ref": "#/components/schemas/JobChange_Meta" } } }, "JobChange_JobChangeSignal": { "type": "object", "required": [ "signalId", "signalType", "occurredAt", "personName", "newRole" ], "properties": { "signalId": { "type": "string", "format": "uuid", "description": "Unique identifier for the signal" }, "signalType": { "type": "string", "description": "Type of signal (always \"job_change\")", "example": "job_change" }, "match_confidence": { "type": "string", "enum": [ "exact", "fuzzy", "none" ], "description": "How this row's company was matched: \"exact\" (via `company_domain` / `company_linkedin_url`), \"fuzzy\" (via `company_name` partial match), or \"none\" (no company identifier in the query)." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the job change occurred" }, "discoveredAt": { "type": "string", "format": "date-time", "description": "When the signal was discovered" }, "personName": { "type": "string", "description": "Person's name (GDPR-masked: first name + last initial only)", "example": "Alex J." }, "personLinkedinUrl": { "type": "string", "nullable": true, "description": "Person's LinkedIn profile URL" }, "companyLinkedinUrl": { "type": "string", "nullable": true, "description": "Company's LinkedIn page URL" }, "newRole": { "type": "string", "description": "New role / job title" }, "postContent": { "type": "string", "nullable": true, "description": "Content of the post announcing the change" }, "takenFrom": { "type": "string", "nullable": true, "description": "URL where the signal was sourced from" }, "source": { "type": "string", "nullable": true, "description": "Source platform", "enum": [ "linkedin", "press_release", "other" ] }, "companyName": { "type": "string", "nullable": true, "description": "Company name (from job change details)" }, "personCurrentTitle": { "type": "string", "nullable": true, "description": "Person's current title as shown on their profile" }, "personHeadline": { "type": "string", "nullable": true, "description": "Person's LinkedIn headline" }, "personLocation": { "type": "string", "nullable": true, "description": "Person's full location string" }, "personCity": { "type": "string", "nullable": true, "description": "Person's city" }, "personCountry": { "type": "string", "nullable": true, "description": "Person's country" }, "personFollowers": { "type": "integer", "nullable": true, "description": "Number of LinkedIn followers" }, "personConnections": { "type": "integer", "nullable": true, "description": "Number of LinkedIn connections" }, "personPosts": { "type": "string", "nullable": true, "description": "JSON-encoded array of recent person posts" }, "companyWebsite": { "type": "string", "nullable": true, "description": "Company website URL" }, "companyIndustry": { "type": "string", "nullable": true, "description": "Company industry" }, "companyCountry": { "type": "string", "nullable": true, "description": "Company HQ country code" }, "companySubcategory": { "type": "string", "nullable": true, "description": "Assigned company subcategory (same vocabulary as the `subcategories` filter)" }, "companyEmployeeCount": { "type": "integer", "nullable": true, "description": "Company employee count" }, "companyFoundedYear": { "type": "integer", "nullable": true, "description": "Company founded year" }, "companyLogoUrl": { "type": "string", "nullable": true, "description": "Company logo URL" }, "companyDescription": { "type": "string", "nullable": true, "description": "Company description" }, "companySpecialties": { "type": "string", "nullable": true, "description": "JSON-encoded array of company specialties" }, "companyCategories": { "type": "string", "nullable": true, "description": "JSON-encoded array of company categories" }, "isFreeAccess": { "type": "boolean", "description": "Whether full data is accessible (always true for authenticated requests)", "example": true }, "companyLogo": { "type": "string", "nullable": true, "description": "Alias of companyLogoUrl for backwards compatibility" }, "sources": { "type": "array", "description": "Source references for this signal", "items": { "$ref": "#/components/schemas/JobChange_Source" } } } }, "JobChange_Source": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the source" }, "sourceType": { "type": "string", "nullable": true, "description": "Type of source", "enum": [ "press_release", "news_article", "social_media", "blog_post", "sec_filing", "crunchbase", "pitchbook" ] } } }, "JobChange_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "totalPages": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "JobChange_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "example": "signals.jobChanges" }, "creditsUsed": { "type": "number", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "Credits remaining after this request" } } }, "JobChange_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "Hiring_HiringSignalsResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Hiring_HiringSignal" } }, "pagination": { "$ref": "#/components/schemas/Hiring_Pagination" }, "meta": { "$ref": "#/components/schemas/Hiring_Meta" } } }, "Hiring_HiringSignal": { "type": "object", "required": [ "id", "jobUrl", "title", "companyName" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the hiring signal" }, "match_confidence": { "type": "string", "enum": [ "exact", "fuzzy", "none" ], "description": "How this row's company was matched: \"exact\" (via `company_domain` / `company_linkedin_url`), \"fuzzy\" (via `company_name` partial match), or \"none\" (no company identifier in the query)." }, "jobId": { "type": "string", "nullable": true, "description": "External job ID from the source platform" }, "jobUrl": { "type": "string", "format": "uri", "description": "URL of the job posting" }, "title": { "type": "string", "description": "Job title" }, "location": { "type": "string", "nullable": true, "description": "Full location string" }, "city": { "type": "string", "nullable": true, "description": "City of the job posting" }, "region": { "type": "string", "nullable": true, "description": "State or region" }, "jobCountry": { "type": "string", "nullable": true, "description": "Country code for the job listing location (not necessarily company HQ)" }, "datePosted": { "type": "string", "format": "date-time", "nullable": true, "description": "When the job was posted" }, "validThrough": { "type": "string", "format": "date-time", "nullable": true, "description": "When the job posting expires" }, "employmentType": { "type": "string", "nullable": true, "description": "Type of employment (e.g., Full-time, Part-time, Contract)" }, "seniorityLevel": { "type": "string", "nullable": true, "description": "Seniority level of the role" }, "jobFunction": { "type": "string", "nullable": true, "description": "Job function / department" }, "industries": { "type": "string", "nullable": true, "description": "Industries associated with the posting" }, "numApplicants": { "type": "string", "nullable": true, "description": "Number of applicants (as string)" }, "descriptionText": { "type": "string", "nullable": true, "description": "Plain text job description" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the signal was ingested" }, "companyId": { "type": "string", "format": "uuid", "description": "Unique identifier for the company" }, "companyName": { "type": "string", "description": "Name of the hiring company" }, "companyWebsite": { "type": "string", "nullable": true, "description": "Company website URL" }, "companyIndustry": { "type": "string", "nullable": true, "description": "Industry of the company" }, "companyCountry": { "type": "string", "nullable": true, "description": "Country code of company HQ" }, "companySubcategory": { "type": "string", "nullable": true, "description": "Assigned company subcategory (same vocabulary as the `subcategories` filter)" }, "companyEmployeeCount": { "type": "integer", "nullable": true, "description": "Number of employees" }, "companyFoundedYear": { "type": "integer", "nullable": true, "description": "Year the company was founded" }, "companyLogoUrl": { "type": "string", "nullable": true, "description": "URL of the company logo" }, "companyDescription": { "type": "string", "nullable": true, "description": "Company description" }, "companySpecialties": { "type": "string", "nullable": true, "description": "JSON-encoded array of company specialties" }, "companyCategories": { "type": "string", "nullable": true, "description": "JSON-encoded array of company categories" }, "isFreeAccess": { "type": "boolean", "description": "Whether full data is accessible (always true for authenticated requests)", "example": true }, "companyLogo": { "type": "string", "nullable": true, "description": "Alias of companyLogoUrl for backwards compatibility" } } }, "Hiring_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "totalPages": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "Hiring_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "example": "signals.hiring" }, "creditsUsed": { "type": "number", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "Credits remaining after this request" } } }, "Hiring_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "Investors_InvestorsResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Investors_Investor" } }, "pagination": { "$ref": "#/components/schemas/Investors_Pagination" }, "meta": { "$ref": "#/components/schemas/Investors_Meta" } } }, "Investors_Investor": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the investor" }, "name": { "type": "string", "description": "Name of the investor or firm" }, "type": { "type": "string", "nullable": true, "description": "Type of investor", "enum": [ "vc", "angel", "pe", "corporate", "government", "accelerator", "family_office", "hedge_fund", "crowdfunding" ] }, "linkedinUrl": { "type": "string", "nullable": true, "description": "LinkedIn company page URL" }, "website": { "type": "string", "nullable": true, "description": "Investor website URL" }, "logoUrl": { "type": "string", "nullable": true, "description": "URL to the investor logo" }, "countries": { "type": "string", "nullable": true, "description": "JSON-encoded array of country codes where the investor operates", "example": "[\"US\",\"IN\"]" }, "ticketSizeMin": { "type": "integer", "nullable": true, "description": "Minimum ticket size in USD" }, "ticketSizeMax": { "type": "integer", "nullable": true, "description": "Maximum ticket size in USD" }, "headquarters": { "type": "string", "nullable": true, "description": "Headquarters location" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the investor record was created" }, "isFreeAccess": { "type": "boolean", "description": "Whether full data is accessible (always true for authenticated requests)", "example": true } } }, "Investors_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "totalPages": { "type": "integer", "minimum": 0 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasNextPage": { "type": "boolean" }, "hasPreviousPage": { "type": "boolean" } } }, "Investors_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "example": "signals.investors" }, "creditsUsed": { "type": "number", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "Credits remaining after this request" } } }, "Investors_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string" } } }, "Companies_CompaniesResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful", "example": true }, "data": { "type": "array", "description": "Array of company records", "items": { "$ref": "#/components/schemas/Companies_Company" } }, "pagination": { "$ref": "#/components/schemas/Companies_Pagination" }, "meta": { "$ref": "#/components/schemas/Companies_Meta" } } }, "Companies_Company": { "type": "object", "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the company", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "description": "Company name", "example": "NextGen Software" }, "slug": { "type": "string", "description": "URL-friendly unique slug for the company", "example": "nextgen-software" }, "description": { "type": "string", "nullable": true, "description": "Company description", "example": "Enterprise SaaS platform for workflow automation." }, "website": { "type": "string", "format": "uri", "nullable": true, "description": "Company website URL", "example": "https://www.nextgensoftware.com" }, "linkedinUrl": { "type": "string", "format": "uri", "nullable": true, "description": "LinkedIn company page URL", "example": "https://www.linkedin.com/company/nextgensoftware" }, "twitterUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Twitter/X profile URL", "example": "https://twitter.com/nextgensoftware" }, "logoUrl": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the company logo", "example": "https://media.licdn.com/dms/image/example.png" }, "industry": { "type": "string", "nullable": true, "description": "Industry sector of the company", "example": "Technology" }, "foundedYear": { "type": "integer", "nullable": true, "description": "Year the company was founded", "example": 2018 }, "headquartersCountry": { "type": "string", "nullable": true, "description": "Country where the company is headquartered", "example": "US" }, "employeeCount": { "type": "integer", "nullable": true, "description": "Number of employees", "example": 250 }, "categories": { "type": "array", "description": "Business categories", "items": { "type": "string" }, "example": [ "Software", "SaaS", "Enterprise" ] }, "keywords": { "type": "array", "description": "Keywords associated with the company", "items": { "type": "string" }, "example": [ "workflow automation", "enterprise", "AI" ] }, "specialties": { "type": "array", "description": "Company specialties", "items": { "type": "string" }, "example": [ "process automation", "integration" ] }, "growthInfo": { "type": "object", "nullable": true, "description": "Headcount growth percentages over various time periods", "properties": { "growth_1m": { "type": "number", "description": "1-month growth percentage", "example": 1.2 }, "growth_3m": { "type": "number", "description": "3-month growth percentage", "example": 3.5 }, "growth_6m": { "type": "number", "description": "6-month growth percentage", "example": 8.1 }, "growth_9m": { "type": "number", "description": "9-month growth percentage", "example": 12 }, "growth_12m": { "type": "number", "description": "12-month growth percentage", "example": 18.5 } } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the company record was created", "example": "2024-06-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the company record was last updated", "example": "2024-11-20T14:00:00Z" } } }, "Companies_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "description": "Current page number", "minimum": 1, "example": 1 }, "totalPages": { "type": "integer", "description": "Total number of pages available", "minimum": 0, "example": 200 }, "totalCount": { "type": "integer", "description": "Total number of records matching the query", "minimum": 0, "example": 4000 }, "hasNextPage": { "type": "boolean", "description": "Indicates if there is a next page", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Indicates if there is a previous page", "example": false } } }, "Companies_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "description": "The endpoint that was called", "example": "companies.list" }, "creditsUsed": { "type": "number", "description": "Number of API credits consumed by this request", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "API credits remaining on the team's balance after this request", "minimum": 0, "example": 4999 } } }, "Companies_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful (always false for errors)", "example": false }, "error": { "type": "string", "description": "Error message describing what went wrong", "example": "Invalid API key" } } }, "People_PeopleResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful", "example": true }, "data": { "type": "array", "description": "Array of matched people", "items": { "$ref": "#/components/schemas/People_Person" } }, "pagination": { "$ref": "#/components/schemas/People_Pagination" }, "meta": { "$ref": "#/components/schemas/People_Meta" } } }, "People_Person": { "type": "object", "required": [ "name", "linkedin_url", "title", "status", "city", "country", "company", "is_latest_signal", "matched_signal" ], "properties": { "name": { "type": "string", "nullable": true, "description": "Person's name, masked for privacy (first name + last initial), e.g. `Sarah K.`", "example": "Sarah K." }, "linkedin_url": { "type": "string", "format": "uri", "nullable": true, "description": "Person's LinkedIn profile URL", "example": "https://www.linkedin.com/in/sarah-k" }, "title": { "type": "string", "nullable": true, "description": "Person's job title", "example": "Chief Technology Officer" }, "status": { "type": "string", "enum": [ "active" ], "description": "Employment status. Always `active` — the endpoint is active-only until `include_former` is supported.", "example": "active" }, "city": { "type": "string", "nullable": true, "description": "Person's city. Only populated for job-change-sourced people; `null` for employee-sourced people.", "example": "Berlin" }, "country": { "type": "string", "nullable": true, "description": "Person's country (ISO 3166-1 alpha-2). Only populated for job-change-sourced people; `null` for employee-sourced people. This is the field the `person_countries` filter matches.", "example": "DE" }, "company": { "$ref": "#/components/schemas/People_PersonCompany" }, "is_latest_signal": { "type": "boolean", "description": "Whether `matched_signal` is also the person's newest overall signal. `false` means an older signal matched your filters while a more recent (non-matching) signal exists.", "example": true }, "matched_signal": { "$ref": "#/components/schemas/People_MatchedSignal" } } }, "People_PersonCompany": { "type": "object", "description": "The company associated with the person and matched signal. Fields may be null when the source record has no linked company identity.", "required": [ "name", "domain", "linkedin_url", "country", "city", "size_band", "industry" ], "properties": { "name": { "type": "string", "nullable": true, "description": "Company name", "example": "NextGen Software" }, "domain": { "type": "string", "nullable": true, "description": "Company website domain (scheme and `www.` stripped)", "example": "nextgensoftware.com" }, "linkedin_url": { "type": "string", "format": "uri", "nullable": true, "description": "LinkedIn company page URL", "example": "https://www.linkedin.com/company/nextgensoftware" }, "country": { "type": "string", "nullable": true, "description": "Company headquarters country (ISO 3166-1 alpha-2)", "example": "NL" }, "city": { "type": "string", "nullable": true, "description": "Company city. Always `null` today — companies do not carry a city field yet.", "example": null }, "size_band": { "type": "string", "nullable": true, "enum": [ "1-10", "11-50", "51-100", "101-250", "251-500", "501-1000", "1000-plus" ], "description": "Company size band derived from employee count. `null` when headcount is unknown.", "example": "101-250" }, "industry": { "type": "string", "nullable": true, "description": "Company industry", "example": "Technology" } } }, "People_MatchedSignal": { "type": "object", "description": "The latest signal that matched the query filters — the person's why-now, always consistent with the filters (not necessarily their newest overall signal; see `is_latest_signal`).", "required": [ "type", "date", "summary", "source_url" ], "properties": { "type": { "type": "string", "enum": [ "funding_round", "acquisition", "job_change" ], "description": "Signal type", "example": "funding_round" }, "date": { "type": "string", "format": "date", "description": "Signal date (YYYY-MM-DD)", "example": "2026-05-12" }, "summary": { "type": "string", "description": "Human-readable summary of the signal", "example": "Series B, $40M led by Accel" }, "source_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the primary source for the signal, when available", "example": "https://techcrunch.com/2026/05/12/nextgen-series-b" } } }, "People_Pagination": { "type": "object", "required": [ "currentPage", "totalPages", "totalCount", "hasNextPage", "hasPreviousPage" ], "properties": { "currentPage": { "type": "integer", "description": "Current page number", "minimum": 1, "example": 1 }, "totalPages": { "type": "integer", "description": "Total number of pages available", "minimum": 0, "example": 12 }, "totalCount": { "type": "integer", "description": "Total number of distinct people matching the query", "minimum": 0, "example": 1183 }, "hasNextPage": { "type": "boolean", "description": "Indicates if there is a next page", "example": true }, "hasPreviousPage": { "type": "boolean", "description": "Indicates if there is a previous page", "example": false } } }, "People_Meta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "description": "The endpoint that was called", "example": "people.list" }, "creditsUsed": { "type": "number", "description": "Number of API credits consumed by this request (0 in count mode)", "minimum": 0, "example": 1 }, "creditsRemaining": { "type": "number", "description": "API credits remaining on the team's balance after this request. Omitted in count mode.", "minimum": 0, "example": 4999 } } }, "People_ErrorResponse": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "type": "boolean", "description": "Indicates if the request was successful (always false for errors)", "example": false }, "error": { "type": "string", "description": "Error message describing what went wrong", "example": "Invalid API key" } } }, "Csv_CSVEnrichmentRequest": { "type": "object", "required": [ "companies" ], "properties": { "fileName": { "type": "string", "description": "Optional label stored on the enrichment job. Defaults to api-companies.json.", "maxLength": 500, "example": "target-accounts.csv" }, "wait": { "type": "boolean", "description": "If true, wait up to timeout seconds and return completed results inline when available.", "default": false }, "timeout": { "type": "integer", "description": "Maximum wait time in seconds when wait=true.", "minimum": 1, "maximum": 30, "default": 30 }, "companies": { "type": "array", "description": "Companies to enrich. Maximum 1,000 companies per request.", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/Csv_CompanyEnrichmentInput" } } } }, "Csv_CompanyEnrichmentInput": { "type": "object", "description": "Company input. Include at least one of company_name, website_url, or linkedin_url. Additional fields are preserved on the enrichment row.", "additionalProperties": true, "properties": { "company_name": { "type": "string", "description": "Company name", "example": "Mollie" }, "companyName": { "type": "string", "description": "Alias for company_name" }, "name": { "type": "string", "description": "Alias for company_name" }, "website_url": { "type": "string", "description": "Company website URL or domain", "example": "mollie.com" }, "websiteUrl": { "type": "string", "description": "Alias for website_url" }, "website": { "type": "string", "description": "Alias for website_url" }, "domain": { "type": "string", "description": "Alias for website_url" }, "linkedin_url": { "type": "string", "description": "Company LinkedIn URL" }, "linkedinUrl": { "type": "string", "description": "Alias for linkedin_url" }, "linkedin": { "type": "string", "description": "Alias for linkedin_url" }, "company_linkedin_url": { "type": "string", "description": "Alias for linkedin_url" } } }, "Csv_CSVEnrichmentCreateResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "oneOf": [ { "$ref": "#/components/schemas/Csv_CSVEnrichmentCreatedJob" }, { "$ref": "#/components/schemas/Csv_CSVEnrichmentJobWithMapping" } ] }, "meta": { "$ref": "#/components/schemas/Csv_CreateMeta" } } }, "Csv_CSVEnrichmentGetResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Csv_CSVEnrichmentJob" }, "meta": { "$ref": "#/components/schemas/Csv_GetMeta" } } }, "Csv_CSVEnrichmentCreatedJob": { "type": "object", "required": [ "jobId", "detectedMapping" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "detectedMapping": { "$ref": "#/components/schemas/Csv_DetectedMapping" } } }, "Csv_CSVEnrichmentJobWithMapping": { "allOf": [ { "$ref": "#/components/schemas/Csv_CSVEnrichmentJob" }, { "type": "object", "required": [ "detectedMapping" ], "properties": { "detectedMapping": { "$ref": "#/components/schemas/Csv_DetectedMapping" } } } ] }, "Csv_CSVEnrichmentJob": { "type": "object", "required": [ "jobId", "status", "progress", "submittedAt", "completedAt", "summary", "results", "nextCursor" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/Csv_CSVEnrichmentStatus" }, "progress": { "$ref": "#/components/schemas/Csv_Progress" }, "submittedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "summary": { "$ref": "#/components/schemas/Csv_Summary" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Csv_EnrichmentResult" } }, "nextCursor": { "type": [ "string", "null" ] }, "error": { "$ref": "#/components/schemas/Csv_JobError" } } }, "Csv_CSVEnrichmentStatus": { "type": "string", "enum": [ "pending", "running", "completed", "failed" ] }, "Csv_Progress": { "type": "object", "required": [ "processed", "total" ], "properties": { "processed": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "Csv_Summary": { "type": "object", "required": [ "totalInputs", "matched", "unmatched", "withFundingSignals", "withAcquisitionSignals", "withHiringSignals", "withJobChangeSignals" ], "properties": { "totalInputs": { "type": "integer", "minimum": 0 }, "matched": { "type": "integer", "minimum": 0 }, "unmatched": { "type": "integer", "minimum": 0 }, "withFundingSignals": { "type": "integer", "minimum": 0 }, "withAcquisitionSignals": { "type": "integer", "minimum": 0 }, "withHiringSignals": { "type": "integer", "minimum": 0 }, "withJobChangeSignals": { "type": "integer", "minimum": 0 } } }, "Csv_EnrichmentResult": { "type": "object", "required": [ "input", "matched", "companyId", "company", "signals" ], "properties": { "input": { "type": "object", "additionalProperties": { "type": "string" } }, "matched": { "type": "boolean" }, "companyId": { "type": [ "string", "null" ], "format": "uuid" }, "company": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "employeeCount": { "type": [ "integer", "null" ] } } }, "signals": { "$ref": "#/components/schemas/Csv_Signals" } } }, "Csv_Signals": { "type": "object", "required": [ "funding", "acquisition", "hiring", "job_change", "investors" ], "properties": { "funding": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "acquisition": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "hiring": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "job_change": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "investors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Csv_DetectedMapping": { "type": "object", "required": [ "companyName", "websiteUrl", "linkedinUrl" ], "properties": { "companyName": { "type": [ "string", "null" ] }, "websiteUrl": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ] } } }, "Csv_JobError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "match_engine_unavailable" ] }, "message": { "type": "string" } } }, "Csv_CreateMeta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "const": "csv.enrichment" }, "creditsUsed": { "type": "integer", "const": 1 }, "creditsRemaining": { "type": "integer", "minimum": 0 } } }, "Csv_GetMeta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "const": "csv.enrichment.get" }, "creditsUsed": { "type": "integer", "const": 0 } } }, "Csv_ErrorResponse": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "invalid_company_payload", "invalid_api_key", "subscription_expired", "insufficient_credits", "rate_limited", "job_not_found", "job_expired", "match_engine_unavailable" ] }, "retryAfter": { "type": "integer", "description": "Seconds until retry is recommended, present on rate limit responses." } } }, "Webhook_EventType": { "type": "string", "description": "Event type a subscription can register for. system.test is accepted but only ever delivered by the Send Test Event endpoint; it never fires automatically.", "enum": [ "funding.created", "acquisition.created", "job_change.created", "hiring.created", "new_company.created", "investor.created", "system.test" ] }, "Webhook_DeliveryStatus": { "type": "string", "description": "Delivery lifecycle status. done = endpoint returned 2xx; failed = non-2xx or network error; pending = recorded but not yet resolved.", "enum": [ "done", "failed", "pending" ] }, "Webhook_WebhookStats": { "type": "object", "required": [ "total_deliveries", "successful_deliveries", "failed_deliveries", "last_success_at", "last_failure_at", "consecutive_failures" ], "properties": { "total_deliveries": { "type": "integer", "minimum": 0 }, "successful_deliveries": { "type": "integer", "minimum": 0 }, "failed_deliveries": { "type": "integer", "minimum": 0 }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "consecutive_failures": { "type": "integer", "minimum": 0 } } }, "Webhook_Webhook": { "type": "object", "description": "A webhook subscription. List/retrieve/update(no rotation)/delete include secret_preview; create and rotate_secret include the full secret instead.", "required": [ "id", "endpoint_url", "event_types", "filters", "active", "created_at", "updated_at", "last_modified_by", "last_modified_via", "stats" ], "properties": { "id": { "type": "string", "description": "Unique webhook ID (UUID)." }, "endpoint_url": { "type": "string", "format": "uri", "description": "HTTPS endpoint that receives deliveries." }, "event_types": { "type": "array", "description": "Event types this subscription is registered for.", "items": { "$ref": "#/components/schemas/Webhook_EventType" } }, "filters": { "type": "object", "description": "Optional string key/value filters that narrow which events are delivered. Recognized keys: countries, jobCountries, categories, search, teamSize, dateFrom, dateTo, funding, roundFlavor, fundingAmount, acquisitionAmount, healthScore. Unrecognized keys are silently ignored — note the round-type key is `funding`, not `round`. For hiring.created events `countries` matches the job listing country OR the company HQ country (same as the REST hiring endpoint), and `jobCountries` matches the job listing country only; `jobCountries` never matches non-hiring events. For investor.created events only countries and search apply. See the Webhooks overview 'Filters' section for value formats.", "additionalProperties": { "type": "string" } }, "active": { "type": "boolean", "description": "Whether the webhook is active. Soft-deleted webhooks are active=false." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "last_modified_by": { "type": [ "string", "null" ], "description": "ID of the user who last modified the webhook. Null if created before audit columns existed." }, "last_modified_via": { "type": [ "string", "null" ], "description": "Where the last change originated.", "enum": [ "api", "dashboard", null ] }, "secret": { "type": "string", "description": "Full HMAC signing secret (UUID). Returned ONLY on create and on update with rotate_secret:true." }, "secret_preview": { "type": "string", "description": "An ellipsis followed by the last 4 characters of the secret (e.g. \"…5a6b\"). Returned on every read instead of the full secret." }, "stats": { "$ref": "#/components/schemas/Webhook_WebhookStats" } } }, "Webhook_Delivery": { "type": "object", "required": [ "id", "event_type", "event_id", "status", "response_status", "response_body", "attempt_count", "delivered_at", "failed_at", "created_at" ], "properties": { "id": { "type": "string", "description": "Delivery ID. Pass to the retry endpoint as deliveryId." }, "event_type": { "$ref": "#/components/schemas/Webhook_EventType" }, "event_id": { "type": "string", "description": "Event ID, stable across the original delivery and any retries — use it to dedupe." }, "status": { "$ref": "#/components/schemas/Webhook_DeliveryStatus" }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP status the endpoint returned, or 0 on a network error, null if not recorded." }, "response_body": { "type": [ "string", "null" ], "description": "First 1000 characters of the endpoint's response body." }, "attempt_count": { "type": "integer", "minimum": 1 }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "failed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "Webhook_WebhookCreateRequest": { "type": "object", "required": [ "endpoint_url", "event_types" ], "description": "Field names accept snake_case (canonical) or camelCase (endpointUrl, eventTypes).", "properties": { "endpoint_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "Destination URL. Must be a valid http/https URL of at most 500 characters. In production, localhost and private/link-local addresses are rejected.", "example": "https://example.com/hooks/signalbase" }, "event_types": { "type": "array", "description": "Event types to subscribe to. Duplicates are removed.", "items": { "$ref": "#/components/schemas/Webhook_EventType" }, "example": [ "funding.created", "hiring.created" ] }, "filters": { "type": "object", "description": "Optional string key/value filters that narrow which events are delivered. Recognized keys: countries, jobCountries, categories, search, teamSize, dateFrom, dateTo, funding, roundFlavor, fundingAmount, acquisitionAmount, healthScore. Unrecognized keys are silently ignored — note the round-type key is `funding`, not `round`. For hiring.created events `countries` matches the job listing country OR the company HQ country (same as the REST hiring endpoint), and `jobCountries` matches the job listing country only; `jobCountries` never matches non-hiring events. For investor.created events only countries and search apply. See the Webhooks overview 'Filters' section for value formats.", "additionalProperties": { "type": "string" }, "example": { "countries": "US,GB", "funding": "seed,series a" } } } }, "Webhook_WebhookUpdateRequest": { "type": "object", "description": "Send any subset of fields. Field names accept snake_case or camelCase (endpointUrl, eventTypes, rotateSecret).", "properties": { "endpoint_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "New destination URL. Same validation as create." }, "event_types": { "type": "array", "description": "Replacement list of subscribed event types.", "items": { "$ref": "#/components/schemas/Webhook_EventType" } }, "filters": { "type": "object", "description": "Replacement filter map. Same recognized keys as on create (countries, categories, search, teamSize, dateFrom, dateTo, funding, roundFlavor, fundingAmount, acquisitionAmount, healthScore); unrecognized keys are ignored.", "additionalProperties": { "type": "string" } }, "active": { "type": "boolean", "description": "Set false to pause, or true to re-enable a soft-deleted webhook." }, "rotate_secret": { "type": "boolean", "description": "If true, generate a new signing secret. The response includes the full new secret once; the old secret stops verifying immediately." } } }, "Webhook_ResponseMeta": { "type": "object", "required": [ "endpoint", "creditsUsed" ], "properties": { "endpoint": { "type": "string", "description": "Endpoint identifier (e.g. webhooks.create)." }, "creditsUsed": { "type": "integer", "minimum": 0, "description": "API credits consumed by this request." } } }, "Webhook_OffsetPagination": { "type": "object", "required": [ "limit", "offset", "count" ], "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer", "description": "Number of items returned in this page." } } }, "Webhook_CursorPagination": { "type": "object", "required": [ "next_cursor", "limit" ], "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when there are no more rows." }, "limit": { "type": "integer" } } }, "Webhook_WebhookCreateResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Webhook_Webhook" }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookGetResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Webhook_Webhook" }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookUpdateResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Webhook_Webhook" }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookListResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook_Webhook" } }, "pagination": { "$ref": "#/components/schemas/Webhook_OffsetPagination" }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookDeleteResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "success", "id", "active" ], "properties": { "success": { "type": "boolean", "const": true }, "id": { "type": "string" }, "active": { "type": "boolean", "const": false } } }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookTestResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "success", "delivery_id", "event_id", "event_type", "response_status", "response_body" ], "properties": { "success": { "type": "boolean", "description": "Whether the endpoint accepted the test event with a 2xx." }, "delivery_id": { "type": "string" }, "event_id": { "type": "string" }, "event_type": { "type": "string", "const": "system.test" }, "response_status": { "type": "integer" }, "response_body": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookDeliveriesResponse": { "type": "object", "required": [ "success", "data", "pagination", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook_Delivery" } }, "pagination": { "$ref": "#/components/schemas/Webhook_CursorPagination" }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_WebhookRetryResponse": { "type": "object", "required": [ "success", "data", "meta" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "delivery_id", "previous_delivery_id", "status", "response_status", "attempt_count", "success" ], "properties": { "delivery_id": { "type": "string", "description": "ID of the new delivery row created by this retry." }, "previous_delivery_id": { "type": "string", "description": "ID of the delivery that was retried." }, "status": { "$ref": "#/components/schemas/Webhook_DeliveryStatus" }, "response_status": { "type": "integer" }, "attempt_count": { "type": "integer", "minimum": 2 }, "success": { "type": "boolean" } } }, "meta": { "$ref": "#/components/schemas/Webhook_ResponseMeta" } } }, "Webhook_ErrorResponse": { "type": "object", "required": [ "success", "error", "code" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string", "description": "Human-readable error message." }, "code": { "type": "string", "enum": [ "bad_request", "invalid_api_key", "subscription_expired", "not_found", "conflict", "rate_limited", "internal_server_error", "internal_error" ] }, "retryAfter": { "type": "integer", "description": "Seconds until a retry is recommended. Present on rate-limit (429) responses." } } } } } }