{ "openapi": "3.0.3", "info": { "title": "Pipecorn API", "version": "2.0.0", "description": "Search companies and people, enrich them with a verified work email and mobile number, and read buying signals.\n\nAuthenticate with your API key in the X-API-KEY header. Enrichment spends credits (an email costs 3, a mobile 30); extraction spends plan quotas.\nA 402 with code insufficient_credits means the credit balance is empty, a 403 with code workspace_limit_exceeded means a workspace admin capped this member, a 422 \"Plan limit reached.\" means an extraction quota ran out, a 429 means slow down.\nResponses from endpoints under the plan rate limit carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; a 429 adds Retry-After. Send an Idempotency-Key header on a POST to retry it without running or paying twice. Async enrichment returns a Location status URL; list endpoints page with cursor.\n\nDocs: https://docs.pipecorn.com/api-reference/overview. Agent guide: https://docs.pipecorn.com/agents.md.\nThe same data is available over MCP at https://mcp.pipecorn.com/mcp.\nSynchronous enrichment, on another host, has its own spec: https://pipecorn.com/openapi/sync-enrichment.json.", "contact": { "name": "Pipecorn", "url": "https://pipecorn.com/contact" }, "termsOfService": "https://pipecorn.com/terms-of-service", "x-logo": { "url": "https://pipecorn.com/assets/logo-pipecorn-square.svg" } }, "servers": [ { "url": "https://app.pipecorn.com/api/v2" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Leads", "description": "Pipecorn Accounts API" }, { "name": "Accounts", "description": "Pipecorn Accounts API" }, { "name": "Enrichments", "description": "Pipecorn List API" }, { "name": "Signals", "description": "Pipecorn Accounts API" }, { "name": "Lists", "description": "Pipecorn List API" }, { "name": "Personas", "description": "Pipecorn Personas API" }, { "name": "Searches", "description": "Pipecorn List API" }, { "name": "Miscellaneous", "description": "Pipecorn Miscellaneous API" }, { "name": "WhatsApp", "description": "Private endpoint to check whether a phone number is reachable on WhatsApp." } ], "paths": { "/leads/single_enrich": { "post": { "operationId": "enrich_person", "tags": [ "Leads" ], "summary": "Enrich a single person", "description": "Enrich a single person with profile and firmographic data.\n\n**Credits:** 1 credit per enrichment. You are only charged when a person is actually resolved — a lookup that matches nothing costs nothing.\n\nIdentify the person either by `linkedin_url`, or by `first_name` + `last_name` + `company_name`.\n\nThis endpoint returns the profile only. Email and phone come from [waterfall enrichment](/api-reference/endpoints/contacts/single_enrich) and are never part of this response.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name", "example": "Mathieu" }, "last_name": { "type": "string", "description": "Last name", "example": "Brun-Picard" }, "company_name": { "type": "string", "description": "Company name", "example": "Pipecorn" }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" } }, "required": [ "first_name", "last_name", "company_name" ] } } } }, "responses": { "200": { "description": "Successfully enriched lead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnrichment" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough enrichment credits for the 1-credit enrichment. Returned before any lookup runs, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/contacts/reverse_lookup": { "post": { "operationId": "reverse_email_lookup", "tags": [ "Leads" ], "summary": "Reverse email lookup", "description": "Find the person behind an email address, professional or personal.\n\n**Credits:** 1 credit per match. You are only charged when a person is found — an email that matches nobody costs nothing and returns `{\"data\": null, \"message\": \"No lead found\"}` with a `200`.\n\nOn a match, the response is the same profile payload as [Enrich people](/api-reference/endpoints/leads/single) (database mode): name, headline, LinkedIn URLs, current position, positions, location and company. It does not include contact data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to look up, professional or personal. Case-insensitive.", "example": "mathieu@prontohq.com" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "The person holding this email, or `{\"data\": null, \"message\": \"No lead found\"}` when nobody matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnrichment" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "`email` is missing or is not a valid email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough enrichment credits for the 1-credit lookup. Returned before any lookup runs, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "Rate limit exceeded: 60 requests per minute per user. The request is refused before any lookup runs, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded. Please wait before retrying." } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/contacts/reverse_phone_lookup": { "post": { "operationId": "reverse_phone_lookup", "tags": [ "Leads" ], "summary": "Reverse phone lookup", "description": "Find the person behind a phone number.\n\n**Credits:** 30 credits per match, the price of a phone. You are only charged when a person is found — a number that matches nobody costs nothing and returns `{\"data\": null, \"message\": \"No lead found\"}` with a `200`.\n\nThe number is matched against the phone numbers found by Pipecorn enrichments. Numbers reported as belonging to someone else, and numbers whose owner opted out, never match.\n\nOn a match, the response is the same profile payload as [Enrich people](/api-reference/endpoints/leads/single) (database mode): name, headline, LinkedIn URLs, current position, positions, location and company. It does not include contact data.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "description": "Phone number to look up, in international format with its country code. Spaces, dots, dashes and parentheses are ignored.", "example": "+33612345678" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "The person holding this phone number, or `{\"data\": null, \"message\": \"No lead found\"}` when nobody matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadEnrichment" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "`phone` is missing, is not a valid phone number, or has no country code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid phone, use the international format (e.g. +33612345678)" } } } }, "402": { "description": "Not enough enrichment credits for the 30-credit lookup. Returned before any lookup runs, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "Rate limit exceeded: 60 requests per minute per user. The request is refused before any lookup runs, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded. Please wait before retrying." } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/leads": { "post": { "operationId": "create_lead_search", "tags": [ "Leads" ], "summary": "Create a new lead search", "description": "Initiates a new lead search based on the provided parameters.\n\n**Rate limit:** 1 request per second, on top of your plan's per-minute request limit", "requestBody": { "description": "Lead search parameters", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewLeadSearch" } } } }, "responses": { "201": { "description": "Lead search created. Results will be delivered to `webhook_url`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the created lead search" }, "search_name": { "type": "string", "description": "Name of the lead search" }, "search_url": { "type": "string", "format": "uri", "description": "The LinkedIn search URL used for extraction" }, "expected_profiles_count": { "type": "integer", "description": "Estimated number of matching profiles" }, "created_at": { "type": "string", "format": "date-time", "description": "When the search was created" }, "custom": { "type": "object", "description": "Custom attributes included with the search", "additionalProperties": true } } } } }, "example": { "message": { "id": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc", "search_name": "Lead search - API - 04/05/2026 12:34", "search_url": "https://www.linkedin.com/sales/search/people?query=(filters%3AList(...))", "expected_profiles_count": 842, "created_at": "2026-05-04T12:34:56Z", "custom": { "hubspot_id": "134567" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - API key doesn't have the required permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "Rate limit exceeded (1 request per second, or your plan's per-minute limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/leads/advanced_search": { "post": { "operationId": "search_leads_by_filters", "tags": [ "Leads" ], "summary": "Search leads by filters", "description": "Run a full lead search using structured filters (titles, locations, industries, companies, function, seniority, tenure, company size, type, lists, relationship and boolean signals). The endpoint builds the underlying query for you, creates an asynchronous `Search`, and streams enriched leads to your `webhook_url`.\n\nAt least one filter (or `keyword`) **must** be provided in addition to `webhook_url`.\n\nBy default the search runs live through LinkedIn Sales Navigator (`live: true`), which requires a connected Sales Navigator integration. Set `live: false` to serve the search — count, preview, and the streamed results — from Pipecorn's people database (Elasticsearch) instead, with no integration required. See the `live` parameter for the relationship/signal filters that database mode does not support.\n\n**Rate limit:** 1 request per second per user, on top of your plan's per-minute request limit.", "requestBody": { "description": "Lead advanced search parameters", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "HTTPS URL that will receive the enriched leads. Required.", "example": "https://hooks.example.com/leads" }, "live": { "type": "boolean", "description": "Data source toggle. `true` (default) runs the search live through LinkedIn Sales Navigator and requires a connected Sales Navigator integration. `false` serves the count, preview, and streamed results from Pipecorn's people database (Elasticsearch) instead, with no integration required. Relationship/signal filters that only exist in LinkedIn's graph are **not supported** with `live: false` and return `422`: `connections_of_profile`, `relationship`, `follows_your_company`, `viewed_your_profile`, `with_shared_experiences`, `posted_on_linkedin`, and `past_colleague`. A non-boolean value returns `422`.", "default": true, "example": true }, "name": { "type": "string", "description": "Friendly name for the search. Defaults to `Lead search - API -
` if omitted.", "example": "EU SaaS VPs of Sales" }, "keyword": { "type": "string", "description": "Free-text keyword applied to the LinkedIn `keywords` query parameter. Spell correction is automatically enabled when a keyword is provided.", "example": "cybersecurity" }, "limit": { "type": "integer", "description": "Cap on the number of leads to enrich. The effective limit is `min(limit, MAX_RESULTS_COUNT)`. If omitted, the estimated search size is used.", "minimum": 1, "example": 500 }, "streaming": { "type": "boolean", "description": "When `true`, leads are POSTed to `webhook_url` as they are scraped/enriched. When `false`, you receive them once the search completes.", "default": false, "example": true }, "scale": { "type": "boolean", "description": "When set to true, increases request volume by omitting the following fields: connections_count, headline, and vanity LinkedIn profile URL. You will still receive a LinkedIn profile URL, but it will use the user ID instead of the vanity URL (e.g., https://www.linkedin.com/in/mathieu-brun-picard/)", "default": false, "example": false }, "custom": { "type": "object", "description": "Arbitrary JSON stored on the search and echoed back in every webhook payload (useful for CRM correlation IDs, etc.).", "additionalProperties": true, "example": { "hubspot_id": "134567" } }, "job_titles": { "type": "array", "items": { "type": "string" }, "description": "Current job titles to include (`CURRENT_TITLE` INCLUDED). Free text matched against the lead's current title.", "example": [ "VP of Sales", "Chief Revenue Officer" ] }, "excluded_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Current job titles to exclude (`CURRENT_TITLE` EXCLUDED).", "example": [ "Intern", "Contractor" ] }, "past_titles": { "type": "array", "items": { "type": "string" }, "description": "Past job titles to include (`PAST_TITLE` INCLUDED).", "example": [ "Account Executive" ] }, "excluded_past_titles": { "type": "array", "items": { "type": "string" }, "description": "Past job titles to exclude (`PAST_TITLE` EXCLUDED).", "example": [ "SDR" ] }, "first_name": { "type": "string", "description": "Lead first name (`FIRST_NAME` INCLUDED). Single string; surrounding whitespace is trimmed. A non-string value returns `422`.", "example": "Jane" }, "last_name": { "type": "string", "description": "Lead last name (`LAST_NAME` INCLUDED). Single string; surrounding whitespace is trimmed. A non-string value returns `422`.", "example": "Doe" }, "included_locations": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn `geoRegion` IDs to include (`REGION` INCLUDED). Resolve names to IDs with the [Location IDs endpoint](/api-reference/endpoints/miscellaneous/location-ids).", "example": [ "101452733", "105015875" ] }, "excluded_locations": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn `geoRegion` IDs to exclude (`REGION` EXCLUDED).", "example": [ "103644278" ] }, "included_industries": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn industry IDs to include (`INDUSTRY` INCLUDED). See the [LinkedIn Industry List](https://docs.google.com/spreadsheets/d/1qTFPVfcSHnL5PU1AcQlzD8mCmfSICKJ4WuU-OBGhkdI/edit?gid=0#gid=0) for the full mapping. Examples: `\"6\"` Technology, Information and Internet · `\"96\"` Software Development · `\"43\"` Financial Services.", "example": [ "6", "96" ] }, "excluded_industries": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn industry IDs to exclude (`INDUSTRY` EXCLUDED).", "example": [ "12" ] }, "included_companies": { "type": "array", "items": { "oneOf": [ { "type": "string", "description": "Numeric LinkedIn organization id (the integer in `urn:li:organization:`)." }, { "type": "integer", "description": "Numeric LinkedIn organization id." }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "Numeric LinkedIn organization id (the integer in `urn:li:organization:`)." } } } ] }, "description": "Companies the lead currently works at (`CURRENT_COMPANY` INCLUDED). Each entry can be a plain LinkedIn organization id (string or integer) or an object with an `id` key.", "example": [ "1441", { "id": "162479" } ] }, "excluded_companies": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } ] }, "description": "Companies to exclude as a current employer (`CURRENT_COMPANY` EXCLUDED). Same shape as `included_companies`.", "example": [ "162479" ] }, "past_companies": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } } ] }, "description": "Companies the lead worked at in the past (`PAST_COMPANY` INCLUDED). Same shape as `included_companies`.", "example": [ { "id": "1441" } ] }, "company_headquarters": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn `geoRegion` IDs for the lead's company headquarters (`COMPANY_HEADQUARTERS`).", "example": [ "103644278" ] }, "included_account_lists": { "type": "array", "items": { "type": "string" }, "description": "Account list IDs to include (`ACCOUNT_LIST` INCLUDED).", "example": [ "12345678" ] }, "excluded_account_lists": { "type": "array", "items": { "type": "string" }, "description": "Account list IDs to exclude (`ACCOUNT_LIST` EXCLUDED).", "example": [ "12345678" ] }, "included_lead_lists": { "type": "array", "items": { "type": "string" }, "description": "Lead list IDs to include (`LEAD_LIST` INCLUDED).", "example": [ "87654321" ] }, "excluded_lead_lists": { "type": "array", "items": { "type": "string" }, "description": "Lead list IDs to exclude (`LEAD_LIST` EXCLUDED).", "example": [ "87654321" ] }, "functions": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26" ] }, "description": "LinkedIn function (department) IDs (`FUNCTION`). Multiple IDs are combined with OR logic.\n\nID → value: 1 Accounting; 2 Administrative; 3 Arts and Design; 4 Business Development; 5 Community and Social Services; 6 Consulting; 7 Education; 8 Engineering; 9 Entrepreneurship; 10 Finance; 11 Healthcare Services; 12 Human Resources; 13 Information Technology; 14 Legal; 15 Marketing; 16 Media and Communication; 17 Military and Protective Services; 18 Operations; 19 Product Management; 20 Program and Project Management; 21 Purchasing; 22 Quality Assurance; 23 Real Estate; 24 Research; 25 Sales; 26 Customer Success and Support.", "example": [ "25" ] }, "seniority_levels": { "type": "array", "items": { "type": "string", "enum": [ "100", "110", "120", "130", "200", "210", "220", "300", "310", "320" ] }, "description": "LinkedIn seniority level IDs (`SENIORITY_LEVEL`).\n\nID → value: 100 In Training; 110 Entry Level; 120 Senior; 130 Strategic; 200 Entry Level Manager; 210 Experienced Manager; 220 Director; 300 Vice President; 310 CXO; 320 Owner / Partner.", "example": [ "300", "310" ] }, "years_of_experience": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8" ] }, "description": "Bucketed total years of experience (`YEARS_OF_EXPERIENCE`). LinkedIn buckets: `\"1\"` Less than 1 year, `\"2\"` 1 to 2 years, `\"3\"` 3 to 5 years, `\"4\"` 6 to 10 years, `\"5\"` More than 10 years (additional buckets `\"6\"`–`\"8\"` are reserved by LinkedIn).", "example": [ "3", "4" ] }, "years_at_current_company": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8" ] }, "description": "Bucketed years at the current company (`YEARS_AT_CURRENT_COMPANY`). Same bucket scale as `years_of_experience`.", "example": [ "2", "3" ] }, "years_in_current_position": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8" ] }, "description": "Bucketed years in the current position (`YEARS_IN_CURRENT_POSITION`). Same bucket scale as `years_of_experience`.", "example": [ "3" ] }, "company_size": { "type": "array", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "description": "Company size ranges to include.", "example": [ "51-200", "201-500", "501-1000" ] }, "company_type": { "type": "array", "items": { "type": "string", "enum": [ "C", "E", "G", "N", "P", "S", "X" ] }, "description": "LinkedIn company type (`COMPANY_TYPE`).\n\nID → value: `C` Public Company; `E` Educational Institution; `G` Government Agency; `N` Non-Profit; `P` Privately Held; `S` Self-Employed; `X` Self-Owned.", "example": [ "P", "C" ] }, "relationship": { "type": "array", "items": { "type": "string", "enum": [ "F", "S", "O", "A" ] }, "description": "Connection relationship to the authenticated LinkedIn account (`RELATIONSHIP`).\n\nID → value: `F` 1st degree; `S` 2nd degree; `O` 3rd degree and beyond; `A` Group members.", "example": [ "S" ] }, "recently_changed_jobs": { "type": "array", "items": { "type": "string", "enum": [ "RPC" ] }, "description": "Restrict to leads who started a new role in the last 90 days (`RECENTLY_CHANGED_JOBS`, Sales Navigator's \"Changed jobs in the last 90 days\" filter). Pass `[\"RPC\"]` to enable; it is the only accepted value and the 90-day window is fixed.", "example": [ "RPC" ] }, "follows_your_company": { "type": "boolean", "description": "When `true`, only include leads who follow your company (`FOLLOWS_YOUR_COMPANY`, id `CF`).", "default": false, "example": false }, "viewed_your_profile": { "type": "boolean", "description": "When `true`, only include leads who viewed the connected LinkedIn account's profile in the last 30 days (`VIEW_YOUR_PROFILE`, id `VYP`). The 30-day window is fixed by LinkedIn.", "default": false, "example": false }, "with_shared_experiences": { "type": "boolean", "description": "When `true`, only include leads sharing experiences with you (`WITH_SHARED_EXPERIENCES`, id `COMM`).", "default": false, "example": false }, "posted_on_linkedin": { "type": "boolean", "description": "When `true`, only include leads who recently posted on LinkedIn (`POSTED_ON_LINKEDIN`, id `RPOL`).", "default": false, "example": true }, "past_colleague": { "type": "boolean", "description": "When `true`, only include past colleagues (`PAST_COLLEAGUE`, id `CL`).", "default": false, "example": false } } }, "example": { "name": "EU SaaS VPs of Sales", "webhook_url": "https://hooks.example.com/leads", "limit": 500, "streaming": true, "job_titles": [ "VP of Sales", "Chief Revenue Officer" ], "seniority_levels": [ "300", "310" ], "functions": [ "25" ], "included_industries": [ "96", "4" ], "included_locations": [ "101452733", "105015875" ], "company_size": [ "51-200", "201-500", "501-1000" ], "years_in_current_position": [ "3", "4" ], "custom": { "hubspot_id": "134567" } } } } }, "responses": { "201": { "description": "Search created. Results will be delivered to `webhook_url`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "UUID of the created Search." }, "search_name": { "type": "string", "description": "Name of the search." }, "search_url": { "type": "string", "format": "uri", "description": "Sales Navigator URL built from your filters." }, "expected_profiles_count": { "type": "integer", "description": "Estimated number of matching profiles before applying `limit`." }, "created_at": { "type": "string", "format": "date-time" }, "custom": { "type": "object", "additionalProperties": true, "description": "Custom attributes echoed back." } } } } }, "example": { "message": { "id": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc", "search_name": "EU SaaS VPs of Sales", "search_url": "https://www.linkedin.com/sales/search/people?query=(filters%3AList(...))", "expected_profiles_count": 842, "created_at": "2026-05-04T12:34:56Z", "custom": { "hubspot_id": "134567" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Missing `webhook_url`, invalid webhook URL, or no filter / keyword provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — invalid API key, or credentials missing/expired on the user account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — API key does not have access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Validation error — a filter has the wrong shape, contains an ID outside the authorized list (functions, seniority levels, industries, company size, company type, relationship, tenure buckets, recently_changed_jobs), `live` is not a boolean, or a relationship/signal filter unsupported in database mode was sent with `live: false`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (1 request per second per user, or your plan's per-minute limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/leads/advanced_search/preview": { "post": { "operationId": "preview_lead_search", "tags": [ "Leads" ], "summary": "Preview", "description": "Run the same filters as `POST /leads/advanced_search` and return a synchronous preview: the total estimated profile count plus the first 25 matching leads. No `Search` is created, no webhook is called, and no credits are consumed.\n\nThis is intended for UI previews, filter validation, and audience sizing before kicking off the real search.\n\nA valid integration is required on the authenticated account, and at least one filter (or `keyword`) **must** be provided. Unlike `POST /leads/advanced_search`, **`webhook_url` is not required**.\n\n**Rate limit:** 1 request per second per user (5 per second with `live: false`), on top of your plan's per-minute request limit.", "requestBody": { "description": "Same filter parameters as `POST /leads/advanced_search`, including `live` (default `true`) to preview from Pipecorn's people database instead of LinkedIn Sales Navigator. `webhook_url`, `name`, `limit`, `streaming`, `scale`, and `custom` are accepted but ignored — the response is always the first 25 results.", "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Accepts the same filter object as `POST /leads/advanced_search`. See that endpoint for the full list of supported filters.", "additionalProperties": true }, "example": { "job_titles": [ "VP of Sales", "Chief Revenue Officer" ], "seniority_levels": [ "300", "310" ], "functions": [ "25" ], "included_industries": [ "96" ], "included_locations": [ "101452733" ] } } } }, "responses": { "200": { "description": "Preview generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Estimated total number of leads matching the filters (not capped to 25)." }, "preview": { "type": "array", "description": "Up to 25 matching leads.", "items": { "type": "object", "properties": { "full_name": { "type": "string", "example": "Ada Lovelace" }, "headline": { "type": "string", "example": "VP of Sales at Acme" }, "current_company": { "type": "string", "example": "Acme" }, "current_title": { "type": "string", "example": "VP of Sales" }, "linkedin_id": { "type": "string", "description": "Numeric LinkedIn member id parsed from the profile entity URN.", "example": "104885158" }, "profile_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/in/urn:li:fs_salesProfile:(ACoAAAxxxx,NAME_SEARCH,abcde)" } } } } } }, "example": { "total_count": 1234, "preview": [ { "full_name": "Ada Lovelace", "headline": "VP of Sales at Acme", "current_company": "Acme", "current_title": "VP of Sales", "linkedin_id": "104885158", "profile_url": "https://www.linkedin.com/in/urn:li:fs_salesProfile:(ACoAAAxxxx,NAME_SEARCH,abcde)" } ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "No filter or `keyword` provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — invalid API key, or credentials missing/expired on the user account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden — API key does not have access to this endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Validation error — a filter has the wrong shape, or contains an ID outside the authorized list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (1 request per second per user, 5 with `live: false`, or your plan's per-minute limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/leads/search": { "post": { "operationId": "search_leads_in_company", "tags": [ "Leads" ], "summary": "Search leads by job title for a specific company", "description": "Searches for leads based on job titles and a company (LinkedIn company ID or URL). Optionally narrow results by location, LinkedIn **function** (department), and **seniority** level using the authorized ID lists below.\n\nBy default the search runs live through LinkedIn (`live: true`) and requires a connected integration. Set `live: false` to resolve the company and matching people from Pipecorn's people database (Elasticsearch) instead, with no LinkedIn call and no integration required.", "requestBody": { "description": "Parameters for lead search by job title", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the lead search", "example": "Software Engineer Search" }, "webhook_url": { "type": "string", "description": "Optional webhook URL to receive results when the search is complete", "example": "https://example.com/webhook" }, "company_linkedin_id": { "type": "string", "description": "The LinkedIn ID of the company (required if company_linkedin_url is not provided)", "example": "1234567890" }, "company_linkedin_url": { "type": "string", "format": "uri", "description": "The LinkedIn URL of the company. Required if company_linkedin_id is not provided)", "example": "https://www.linkedin.com/company/pipecorn" }, "job_titles": { "type": "array", "items": { "type": "string" }, "description": "List of job titles to search for. Cannot be combined with `persona_id` — pass one or the other.", "example": [ "Software Engineer", "Product Manager" ] }, "excluded_job_titles": { "type": "array", "items": { "type": "string" }, "description": "List of job titles to exclude from the search. Cannot be combined with `persona_id` — pass one or the other.", "example": [ "Intern", "Contractor" ] }, "persona_id": { "type": "string", "format": "uuid", "description": "Optional. UUID of a saved Pipecorn Persona. When provided, `job_titles` and `excluded_job_titles` are derived from the persona and must not be passed in the request — doing so returns `422`. The persona must belong to the authenticated user.", "example": "1f6b0f5a-2d8e-4c3a-9b8f-1a2b3c4d5e6f" }, "included_locations": { "type": "array", "items": { "type": "string" }, "description": "List of Location IDs that were included in the search", "example": [ "105015875", "102221843" ] }, "excluded_locations": { "type": "array", "items": { "type": "string" }, "description": "List of Location IDs that were excluded from the search", "example": [ "103644278" ] }, "functions": { "type": "array", "items": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26" ] }, "description": "Optional. Filter by LinkedIn function (job function / department). Each value must be one of the authorized function IDs below. Omit or pass an empty array to not filter by function. Multiple IDs are combined with OR logic.\n\nID → value: 1 Accounting; 2 Administrative; 3 Arts and Design; 4 Business Development; 5 Community and Social Services; 6 Consulting; 7 Education; 8 Engineering; 9 Entrepreneurship; 10 Finance; 11 Healthcare Services; 12 Human Resources; 13 Information Technology; 14 Legal; 15 Marketing; 16 Media and Communication; 17 Military and Protective Services; 18 Operations; 19 Product Management; 20 Program and Project Management; 21 Purchasing; 22 Quality Assurance; 23 Real Estate; 24 Research; 25 Sales; 26 Customer Success and Support.", "example": [ "13", "15" ] }, "seniority_levels": { "type": "array", "items": { "type": "string", "enum": [ "100", "110", "120", "130", "200", "210", "220", "300", "310", "320" ] }, "description": "Optional. Filter by LinkedIn seniority level. Each value must be one of the authorized seniority IDs below. Omit or pass an empty array to not filter by seniority. Multiple IDs are combined with OR logic.\n\nID → value: 100 In Training; 110 Entry Level; 120 Senior; 130 Strategic; 200 Entry Level Manager; 210 Experienced Manager; 220 Director; 300 Vice President; 310 CXO; 320 Owner / Partner.", "example": [ "220", "300" ] }, "streaming": { "type": "boolean", "description": "When set to true, leads will be sent individually to the webhook_url as they are found. This is ideal for integration with platforms like Clay that process leads in real-time.", "default": false, "example": true }, "custom": { "type": "object", "description": "Custom fields to include with the lead search that will be returned in the webhook (like crm id, etc.)", "additionalProperties": true, "example": { "hubspot_id": "134567" } }, "limit": { "type": "integer", "description": "Optional parameter to limit the number of results returned. If not specified, all matching leads will be returned.", "minimum": 1, "example": 100 }, "scale": { "type": "boolean", "description": "When set to true, increases request volume by omitting the following fields: connections_count, headline, and vanity LinkedIn profile URL. You will still receive a LinkedIn profile URL, but it will use the user ID instead of the vanity URL (e.g., https://www.linkedin.com/in/mathieu-brun-picard/).", "default": false, "example": true }, "live": { "type": "boolean", "description": "Data source toggle. `true` (default) runs the search live through LinkedIn and requires a connected integration. `false` resolves the company and matching people from Pipecorn's people database (Elasticsearch) instead and streams them to your webhook, with no LinkedIn call and no integration required. A non-boolean value returns `422`.", "default": true, "example": true } }, "allOf": [ { "oneOf": [ { "required": [ "company_linkedin_id" ] }, { "required": [ "company_linkedin_url" ] } ] }, { "anyOf": [ { "required": [ "job_titles" ] }, { "required": [ "excluded_job_titles" ] }, { "required": [ "functions" ] }, { "required": [ "seniority_levels" ] }, { "required": [ "included_locations" ] }, { "required": [ "excluded_locations" ] }, { "required": [ "persona_id" ] } ] } ] } } } }, "responses": { "201": { "description": "Search initiated successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the created lead search" }, "search_name": { "type": "string", "description": "Name of the lead search" }, "search_url": { "type": "string", "format": "uri", "description": "The LinkedIn search URL used for extraction. Omitted with `live: false`." }, "expected_profiles_count": { "type": "integer", "description": "Estimated number of matching profiles" }, "created_at": { "type": "string", "format": "date-time", "description": "When the search was created" }, "custom": { "type": "object", "description": "Custom attributes included with the search", "additionalProperties": true } } } } }, "example": { "message": { "id": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc", "search_name": "Engineering leaders at Acme", "search_url": "https://www.linkedin.com/sales/search/people?query=(filters%3AList(...))", "expected_profiles_count": 842, "created_at": "2026-05-04T12:34:56Z", "custom": { "hubspot_id": "134567" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "401": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden - API key doesn't have the required permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Validation error — for example `functions` or `seniority_levels` must be arrays, or they contain IDs that are not in the authorized lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable validation message", "example": "Invalid function IDs: 99. Valid IDs are: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26" } } } } } }, "429": { "description": "Rate limit exceeded. With `live: false` your plan's per-minute limit applies; live searches are exempt but can be rate limited by LinkedIn.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/": { "post": { "operationId": "extract_account_search", "tags": [ "Accounts" ], "summary": "Extract account search results", "description": "Extract company accounts from a LinkedIn Sales Navigator search URL and process them asynchronously.\n\n**Rate limit:** 20 requests per minute, on top of your plan's per-minute request limit\n\nThis endpoint creates an import job that will process the search results in the background. Results will be sent to the specified webhook URL when processing is complete.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "search_url": { "type": "string", "format": "uri", "description": "LinkedIn Sales Navigator company search URL. Must start with 'https://www.linkedin.com/sales/search/company'", "example": "https://www.linkedin.com/sales/search/company?query=(filters%3AList((type%3AANNUAL_REVENUE%2CrangeValue%3A(min%3A10%2Cmax%3A100)%2CselectedSubFilter%3AUSD)%2C(type%3AINDUSTRY%2Cvalues%3AList((id%3A6%2Ctext%3ATechnologie%252C%2520information%2520et%2520Internet%2CselectionType%3AINCLUDED)))))&sessionId=uYap7SN9RS6itaRp2Vt7Xg%3D%3D&viewAllFilters=true" }, "name": { "type": "string", "description": "Name for the import job", "example": "Tech Companies 10M-100M Revenue" }, "webhook_url": { "type": "string", "format": "uri", "description": "Webhook URL to receive the processed results", "example": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8" }, "streaming": { "type": "boolean", "description": "Enable streaming mode for real-time results", "default": false, "example": false }, "custom": { "type": "object", "description": "Custom attributes to associate with the import", "example": { "source": "api", "campaign": "q1_outreach" } }, "limit": { "type": "integer", "description": "Maximum number of accounts to extract", "example": 100 } }, "required": [ "search_url", "name", "webhook_url" ] }, "example": { "search_url": "https://www.linkedin.com/sales/search/company?query=(revenueRange:%22%2410M-%24100M%22%20AND%20employeeCountRange:%2211-50%22%20AND%20industry:%22Technology%2C%20Information%20and%20Internet%22)", "name": "Tech Companies 10M-100M Revenue", "webhook_url": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8", "streaming": false, "limit": 100, "custom": { "source": "api", "campaign": "q1_outreach" } } } } }, "responses": { "201": { "description": "Import job created successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the import job", "example": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc" }, "import_name": { "type": "string", "description": "Name of the import job", "example": "Tech Companies 10M-100M Revenue" }, "import_url": { "type": "string", "format": "uri", "description": "The processed search URL used for extraction", "example": "https://www.linkedin.com/sales-api/salesApiLeadSearch?query=(revenueRange:%22%2410M-%24100M%22%20AND%20employeeCountRange:%2211-50%22%20AND%20industry:%22Technology%2C%20Information%20and%20Internet%22)" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp of the import job", "example": "2024-01-15T10:30:00Z" }, "limit": { "type": "integer", "description": "Maximum number of companies to import, when `limit` was sent", "example": 500 }, "custom": { "type": "object", "description": "Custom attributes associated with the import", "example": { "source": "api", "campaign": "q1_outreach" } } } } } }, "example": { "message": { "id": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc", "import_name": "Tech Companies 10M-100M Revenue", "import_url": "https://www.linkedin.com/sales-api/salesApiLeadSearch?query=(revenueRange:%22%2410M-%24100M%22%20AND%20employeeCountRange:%2211-50%22%20AND%20industry:%22Technology%2C%20Information%20and%20Internet%22)", "created_at": "2024-01-15T10:30:00Z", "limit": 500, "custom": { "source": "api", "campaign": "q1_outreach" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_required_keys": { "summary": "Missing required keys", "value": { "error": "Missing required keys: search_url, name, webhook_url" } }, "invalid_url_format": { "summary": "Invalid URL format", "value": { "error": "Invalid URL format. Please provide a valid LinkedIn company search URL" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Plan limit reached, or the import could not be saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Can't proceed with the request. Plan limit reached." } } } }, "429": { "description": "Rate limit exceeded (20 requests per minute, or your plan's per-minute limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded. Please wait before retrying." } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal server error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/single_enrich": { "post": { "operationId": "enrich_account", "tags": [ "Accounts" ], "summary": "Enrich a single company account", "description": "Enrich a single company account with firmographic data.\n\n**Credits:** 1 credit per enrichment. You are only charged when a company is actually resolved — a lookup that matches nothing costs nothing.\n\nIdentify the company with any of `company_linkedin_url`, `domain` or `name`. The more you provide, the more precisely the account is matched.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn company profile URL (regular or Sales Navigator)", "example": "https://linkedin.com/company/pipecorn" }, "name": { "type": "string", "description": "Company name", "example": "Pipecorn" }, "domain": { "type": "string", "description": "Company website domain", "example": "pipecorn.com" }, "country": { "type": "string", "description": "Two-letter ISO country code (ISO 3166-1 alpha-2). Examples: FR (France), US (United States), GB (United Kingdom), DE (Germany), ES (Spain), IT (Italy)", "example": "FR" } } } } } }, "responses": { "200": { "description": "Successfully enriched company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountEnrichment" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough enrichment credits for the 1-credit enrichment. Returned before any lookup runs, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/count_profiles": { "post": { "operationId": "count_account_profiles", "tags": [ "Accounts" ], "summary": "Count matching profiles", "description": "Count matching profiles based on job titles and locations.\n\n**Rate limit:** 20 requests per second, on top of your plan's per-minute request limit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title_to_include": { "type": "array", "items": { "type": "string" }, "description": "List of job titles that were included in the search", "example": [ "Software Engineer", "Developer" ] }, "title_to_exclude": { "type": "array", "items": { "type": "string" }, "description": "List of job titles that were excluded from the search", "example": [ "Junior" ] }, "included_locations": { "type": "array", "items": { "type": "string" }, "description": "List of Location IDs that were included in the search", "example": [ "105015875", "102221843" ] }, "excluded_locations": { "type": "array", "items": { "type": "string" }, "description": "List of Location IDs that were excluded from the search", "example": [ "103644278" ] } }, "oneOf": [ { "type": "object", "required": [ "company_linkedin_id" ], "properties": { "company_linkedin_id": { "type": "string", "description": "LinkedIn company identifier", "example": "1234567" } } }, { "type": "object", "required": [ "company_linkedin_url" ], "properties": { "company_linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn company profile URL (regular or Sales Navigator)", "example": "https://www.linkedin.com/company/microsoft" } } } ] } } } }, "responses": { "200": { "description": "Successfully counted matching profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of matching profiles", "example": 26 }, "title_to_include": { "type": "array", "items": { "type": "string" }, "description": "List of job titles that were included in the search", "example": [ "Software Engineer", "Developer" ] }, "title_to_exclude": { "type": "array", "items": { "type": "string" }, "description": "List of job titles that were excluded from the search", "example": [ "Junior" ] }, "included_locations": { "type": "array", "items": { "type": "string" }, "description": "List of Location IDs that were included in the search", "example": [ "105015875", "102221843" ] }, "excluded_locations": { "type": "array", "items": { "type": "string" }, "description": "List of Location IDs that were excluded from the search", "example": [ "103644278" ] } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "Rate limit exceeded (20 requests per second, or your plan's per-minute limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/search": { "post": { "operationId": "search_accounts_by_filters", "tags": [ "Accounts" ], "summary": "Search accounts by filters", "description": "Search and extract company accounts based on industry, location, size, and keyword filters. This endpoint processes results asynchronously and sends them to your webhook.\n\nBy default the search runs live through LinkedIn Sales Navigator (`live: true`), which requires a connected Sales Navigator integration. Set `live: false` to serve everything from Pipecorn's companies database (Elasticsearch) instead, with no integration required.\n\n**Rate limit:** your plan's per-minute request limit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "Webhook URL to receive the processed results", "example": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8" }, "name": { "type": "string", "description": "Name for the import job", "example": "Tech Companies in US" }, "included_industries": { "type": "array", "items": { "type": "string" }, "description": "List of industry IDs to include in the search", "example": [ "4", "6", "96" ] }, "excluded_industries": { "type": "array", "items": { "type": "string" }, "description": "List of industry IDs to exclude from the search", "example": [ "12" ] }, "included_locations": { "type": "array", "items": { "type": "string" }, "description": "List of location IDs to include in the search. Use the /locations endpoint to get valid location IDs", "example": [ "103644278", "105015875" ] }, "excluded_locations": { "type": "array", "items": { "type": "string" }, "description": "List of location IDs to exclude from the search", "example": [ "102221843" ] }, "company_size": { "type": "array", "items": { "type": "string", "enum": [ "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "description": "Company size ranges to include", "example": [ "11-50", "51-200" ] }, "keyword": { "type": "string", "description": "Keyword to search for in company names or descriptions", "example": "saas" }, "min_revenue": { "type": "number", "description": "Minimum annual revenue in millions. Valid values: 0, 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000", "enum": [ 0, 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000 ], "example": 10 }, "max_revenue": { "type": "number", "description": "Maximum annual revenue in millions. Valid values: 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000, 1001 (where 1001 represents $1B+)", "enum": [ 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000, 1001 ], "example": 50 }, "revenue_currency": { "type": "string", "description": "Currency code for revenue values. Defaults to USD if not specified", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "JPY", "CNY", "INR", "BRL", "SEK", "NOK", "DKK", "SGD", "HKD", "NZD", "THB", "IDR", "TRY", "TWD", "ILS", "AED", "RUB" ], "default": "USD", "example": "USD" }, "limit": { "type": "integer", "description": "Maximum number of accounts to extract (default: 1000)", "example": 100 }, "streaming": { "type": "boolean", "description": "Enable streaming mode for real-time results", "default": false, "example": false }, "live": { "type": "boolean", "description": "Data source toggle. `true` (default) searches live through LinkedIn Sales Navigator and requires a connected Sales Navigator integration. `false` serves the count, preview, and extracted accounts from Pipecorn's companies database (Elasticsearch) instead, with no integration required. A non-boolean value returns `422`.", "default": true, "example": true } }, "required": [ "webhook_url" ] }, "example": { "webhook_url": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8", "name": "Tech Companies in US", "included_industries": [ "6" ], "excluded_industries": [ "12" ], "included_locations": [ "103644278" ], "company_size": [ "51-200", "201-500" ], "keyword": "saas", "min_revenue": 10, "max_revenue": 100, "revenue_currency": "USD", "limit": 500, "streaming": false } } } }, "responses": { "201": { "description": "Account search started successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Account search started successfully. You will receive the results on your webhook shortly." }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the import job", "example": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc" }, "total": { "type": "integer", "description": "Total number of accounts that will be processed", "example": 342 }, "preview": { "type": "array", "description": "Preview of the first 10 matching accounts", "items": { "type": "object", "properties": { "company_name": { "type": "string", "example": "Pipecorn" }, "industry": { "type": "string", "example": "Technology, Information and Internet" }, "linkedin_id": { "type": "string", "example": "104885158" }, "linkedin_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/company/104885158" } } } } } }, "example": { "message": "Account search started successfully. You will receive the results on your webhook shortly.", "id": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc", "total": 342, "preview": [ { "company_name": "Pipecorn", "industry": "Technology, Information and Internet", "linkedin_id": "104885158", "linkedin_url": "https://www.linkedin.com/company/104885158" } ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Missing webhook URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_webhook": { "summary": "Missing webhook URL", "value": { "error": "webhook_url key is required in your payload" } } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Invalid filter values (company size, locations, revenue), or plan limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_company_size": { "summary": "Invalid company size", "value": { "error": "Invalid company_size values", "invalid_sizes": [ "10-50" ], "valid_formats": [ "Self-employed", "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] } }, "invalid_location": { "summary": "Invalid location format", "value": { "error": { "error": "Invalid location format", "message": "Locations must be provided as an array of ids", "example": [ "123" ] } } }, "invalid_min_revenue": { "summary": "Invalid min_revenue value", "value": { "error": { "error": "Invalid min_revenue value", "message": "min_revenue must be one of: 0, 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000", "valid_values": [ 0, 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000 ] } } }, "invalid_max_revenue": { "summary": "Invalid max_revenue value", "value": { "error": { "error": "Invalid max_revenue value", "message": "max_revenue must be one of: 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000, 1001", "valid_values": [ 0.5, 1, 2.5, 5, 10, 20, 50, 100, 500, 1000, 1001 ] } } }, "invalid_revenue_currency": { "summary": "Invalid revenue_currency", "value": { "error": { "error": "Invalid revenue_currency", "message": "revenue_currency must be one of: USD, AED, AUD, BRL, CAD, CNY, DKK, EUR, GBP, HKD, IDR, ILS, INR, JPY, NOK, NZD, RUB, SEK, SGD, THB, TRY, TWD", "valid_currencies": [ "USD", "AED", "AUD", "BRL", "CAD", "CNY", "DKK", "EUR", "GBP", "HKD", "IDR", "ILS", "INR", "JPY", "NOK", "NZD", "RUB", "SEK", "SGD", "THB", "TRY", "TWD" ] } } }, "plan_limit": { "summary": "Plan limit reached", "value": { "error": "Can't proceed with the request. Plan limit reached." } } } } } }, "429": { "description": "Rate limit exceeded (your plan's per-minute limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded. Please wait before retrying." } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Internal server error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/search/preview": { "post": { "operationId": "preview_account_search", "tags": [ "Accounts" ], "summary": "Preview", "description": "Run the same filters as `POST /accounts/search` and return a synchronous preview: the total estimated account count plus the first 25 matching companies. No `Import` is created, no webhook is called, and no credits are consumed.\n\nThis is intended for UI previews, filter validation, and audience sizing before kicking off the real search. Unlike `POST /accounts/search`, **`webhook_url` is not required**.\n\n**Rate limit:** your plan's per-minute request limit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Accepts the same filter object as `POST /accounts/search` (`included_industries`, `excluded_industries`, `included_locations`, `excluded_locations`, `company_size`, `keyword`, `min_revenue`, `max_revenue`, `revenue_currency`, etc.), including `live` (default `true`) to preview from Pipecorn's companies database instead of LinkedIn Sales Navigator. `webhook_url`, `name`, `limit`, and `streaming` are accepted but ignored — the response is always the first 25 results.", "additionalProperties": true }, "example": { "included_industries": [ "6", "96" ], "included_locations": [ "103644278" ], "company_size": [ "51-200", "201-500" ], "keyword": "saas" } } } }, "responses": { "200": { "description": "Preview generated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Estimated total number of accounts matching the filters (not capped to 25)." }, "preview": { "type": "array", "description": "Up to 25 matching accounts.", "items": { "type": "object", "properties": { "company_name": { "type": "string", "example": "Pipecorn" }, "industry": { "type": "string", "example": "Technology, Information and Internet" }, "linkedin_id": { "type": "string", "example": "104885158" }, "linkedin_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/company/104885158" } } } } } }, "example": { "total_count": 4321, "preview": [ { "company_name": "Pipecorn", "industry": "Technology, Information and Internet", "linkedin_id": "104885158", "linkedin_url": "https://www.linkedin.com/company/104885158" } ] } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid filter shape (company size, location, revenue, etc.).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized — invalid API key or missing credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "Rate limit exceeded (your plan's per-minute limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/headcount": { "post": { "operationId": "get_department_headcount", "tags": [ "Accounts" ], "summary": "Get company headcount by department", "description": "Retrieve headcount information for specified departments or all departments if none specified.\n\nBy default the data comes live from LinkedIn (`live: true`) and includes 3/6/12-month evolution per department, as documented below. Set `live: false` to answer from Pipecorn's companies database (Elasticsearch) instead, with no integration required. The `live: false` response is a current snapshot only (no evolution) in a different shape:\n\n```json\n{\n \"total_headcount\": 18769,\n \"departments\": {\n \"Engineering\": { \"current_headcount\": 8681 },\n \"Sales\": { \"current_headcount\": 6258 }\n }\n}\n```\n\n**Rate limit:** 20 requests per second, on top of your plan's per-minute request limit", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_linkedin_id": { "type": "string", "description": "LinkedIn company identifier", "example": "1818" }, "departments": { "type": "array", "example": [ "Engineering", "Sales", "Finance" ], "items": { "type": "string", "enum": [ "Accounting", "Administrative", "Arts and Design", "Business Development", "Community and Social Services", "Consulting", "Customer Success and Support", "Education", "Engineering", "Entrepreneurship", "Finance", "Healthcare Services", "Human Resources", "Information Technology", "Legal", "Marketing", "Media and Communication", "Military and Protective Services", "Operations", "Product Management", "Program and Project Management", "Purchasing", "Quality Assurance", "Real Estate", "Research", "Sales" ] }, "description": "List of departments to get headcount for. If not provided, returns data for all departments." }, "live": { "type": "boolean", "description": "Data source toggle. `true` (default) returns the live department headcount with 3/6/12-month evolution from LinkedIn. `false` answers from Pipecorn's companies database (Elasticsearch) instead — no integration required — returning only a current headcount snapshot (`total_headcount` plus `departments` with `current_headcount`), without any evolution data. A non-boolean value returns `422`.", "default": true, "example": true } }, "required": [ "company_linkedin_id" ] } } } }, "responses": { "200": { "description": "Successfully retrieved headcount data", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "object", "properties": { "3_months_evolution": { "type": "object", "properties": { "base_headcount": { "type": "integer", "description": "Base headcount value" }, "current_headcount": { "type": "integer", "description": "Current headcount value" }, "headcount_gain": { "type": "integer", "description": "Headcount gain" }, "headcount_gain_percentage": { "type": "integer", "description": "Headcount gain percentage" } } }, "6_months_evolution": { "type": "object", "properties": { "base_headcount": { "type": "integer", "description": "Base headcount value" }, "current_headcount": { "type": "integer", "description": "Current headcount value" }, "headcount_gain": { "type": "integer", "description": "Headcount gain" }, "headcount_gain_percentage": { "type": "integer", "description": "Headcount gain percentage" } } }, "12_months_evolution": { "type": "object", "properties": { "base_headcount": { "type": "integer", "description": "Base headcount value" }, "current_headcount": { "type": "integer", "description": "Current headcount value" }, "headcount_gain": { "type": "integer", "description": "Headcount gain" }, "headcount_gain_percentage": { "type": "integer", "description": "Headcount gain percentage" } } } } } }, "example": { "Engineering": { "3_months_evolution": { "base_headcount": 8611, "current_headcount": 8681, "headcount_gain": 70, "headcount_gain_percentage": 1 }, "6_months_evolution": { "base_headcount": 8412, "current_headcount": 8681, "headcount_gain": 269, "headcount_gain_percentage": 3 }, "12_months_evolution": { "base_headcount": 8153, "current_headcount": 8681, "headcount_gain": 528, "headcount_gain_percentage": 6 } }, "Finance": { "3_months_evolution": { "base_headcount": 2801, "current_headcount": 2830, "headcount_gain": 29, "headcount_gain_percentage": 1 }, "6_months_evolution": { "base_headcount": 2774, "current_headcount": 2830, "headcount_gain": 56, "headcount_gain_percentage": 2 }, "12_months_evolution": { "base_headcount": 2659, "current_headcount": 2830, "headcount_gain": 171, "headcount_gain_percentage": 6 } }, "Sales": { "3_months_evolution": { "base_headcount": 6130, "current_headcount": 6258, "headcount_gain": 128, "headcount_gain_percentage": 2 }, "6_months_evolution": { "base_headcount": 5914, "current_headcount": 6258, "headcount_gain": 344, "headcount_gain_percentage": 6 }, "12_months_evolution": { "base_headcount": 5549, "current_headcount": 6258, "headcount_gain": 709, "headcount_gain_percentage": 13 } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "details": { "invalid_departments": [ "Engineers" ], "valid_departments": [ "Accounting", "Administrative", "Arts and Design", "Business Development", "Community and Social Services", "Consulting", "Education", "Engineering", "Entrepreneurship", "Finance", "Healthcare Services", "Human Resources", "Information Technology", "Legal", "Marketing", "Media and Communication", "Military and Protective Services", "Operations", "Product Management", "Program and Project Management", "Purchasing", "Quality Assurance", "Real Estate", "Research", "Sales", "Customer Success and Support" ] }, "message": "Please use only valid department values from the provided list." } } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "description": "Rate limit exceeded (20 requests per second, or your plan's per-minute limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/company_hiring": { "post": { "operationId": "get_company_job_postings", "tags": [ "Accounts" ], "summary": "Get company job postings", "description": "Retrieve the list of open job postings indexed for a company.\n\n**Credits:** 1 credit per job returned. You are only charged for the jobs actually returned, and never for more jobs than your available credits allow. A lookup that returns no jobs costs nothing.\n\n**Rate limit:** 5 requests per second (exempt from the per-plan limit)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_domain": { "type": "string", "description": "Company website domain", "example": "notion.so" }, "company_name": { "type": "string", "description": "Company name", "example": "Notion" }, "company_linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn company URL", "example": "https://www.linkedin.com/company/notionhq/" }, "posted_within_days": { "type": "integer", "enum": [ 7, 30, 60, 90, 180 ], "default": 30, "description": "Only return jobs posted within the last N days. Must be one of the selectable look-back windows: 7, 30, 60, 90, or 180. Defaults to 30 when omitted; any other value returns 422.", "example": 30 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of jobs to return. A positive integer capped at 100. Because billing is 1 credit per job, use this to bound how many credits a single lookup can spend. Only enough pages to satisfy the limit are fetched.", "example": 10 }, "full_description": { "type": "boolean", "default": false, "description": "When true, return each job's full description. Defaults to false, in which case descriptions are truncated to a 300-character snippet.", "example": false }, "job_title_keywords": { "type": "array", "items": { "type": "string" }, "description": "Only return jobs whose title matches one of these keywords.", "example": [ "engineer", "developer" ] }, "excluded_job_title_keywords": { "type": "array", "items": { "type": "string" }, "description": "Exclude jobs whose title matches one of these keywords.", "example": [ "intern" ] }, "job_description_keywords": { "type": "array", "items": { "type": "string" }, "description": "Only return jobs whose description contains one of these keywords.", "example": [ "rails", "ruby" ] }, "excluded_job_description_keywords": { "type": "array", "items": { "type": "string" }, "description": "Exclude jobs whose description contains one of these keywords.", "example": [ "php" ] }, "job_country_codes": { "type": "array", "items": { "type": "string" }, "description": "Only return jobs located in these countries. 2-letter ISO 3166-1 alpha-2 country codes (e.g. US, FR); case-insensitive.", "example": [ "US", "FR" ] }, "excluded_job_country_codes": { "type": "array", "items": { "type": "string" }, "description": "Exclude jobs located in these countries. 2-letter ISO 3166-1 alpha-2 country codes (e.g. US, FR); case-insensitive.", "example": [ "CA" ] } } }, "examples": { "by_domain": { "summary": "Lookup by domain", "value": { "company_domain": "notion.so" } }, "by_linkedin_url": { "summary": "Lookup by LinkedIn URL", "value": { "company_linkedin_url": "https://www.linkedin.com/company/notionhq/" } }, "by_name": { "summary": "Lookup by name", "value": { "company_name": "Notion" } }, "with_posted_within_days": { "summary": "Filter by recency", "value": { "company_domain": "notion.so", "posted_within_days": 30 } }, "with_filters_and_limit": { "summary": "Filter by title and country with a limit", "value": { "company_domain": "notion.so", "limit": 10, "full_description": false, "job_title_keywords": [ "engineer", "developer" ], "excluded_job_title_keywords": [ "intern" ], "job_country_codes": [ "US", "FR" ] } } } } } }, "responses": { "200": { "description": "Successfully retrieved job postings", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_jobs": { "type": "integer", "description": "Total number of matching job postings (may exceed the number returned)", "example": 42 }, "truncated": { "type": "boolean", "description": "True when more jobs matched than were returned (because of the limit, the 100-job ceiling, or your available credits).", "example": true }, "company": { "type": "object", "description": "The hiring company, resolved from the first matching job.", "properties": { "name": { "type": "string", "example": "Acme" }, "domain": { "type": "string", "example": "acme.com" }, "linkedin_url": { "type": "string", "format": "uri", "example": "https://linkedin.com/company/acme" } } }, "jobs": { "type": "array", "description": "List of job postings", "items": { "type": "object", "properties": { "job_title": { "type": "string", "description": "Title of the job posting", "example": "Senior Backend Engineer" }, "job_url": { "type": "string", "format": "uri", "description": "URL of the job posting", "example": "https://example.com/jobs/1" }, "job_location": { "type": "string", "description": "Location of the job posting", "example": "Paris France" }, "employment_statuses": { "type": "array", "items": { "type": "string" }, "description": "Employment statuses for the job (e.g. full_time, part_time)", "example": [ "full_time" ] }, "date_posted": { "type": "string", "format": "date", "description": "Date the job was posted", "example": "2026-05-30" }, "description": { "type": "string", "description": "Job description. Truncated to a 300-character snippet unless full_description is true.", "example": "Build cool stuff with Rails." }, "hiring_team": { "type": "array", "description": "List of people involved in hiring for this job", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Alice Doe" }, "title": { "type": "string", "example": "Engineering Manager" }, "linkedin_url": { "type": "string", "format": "uri", "example": "https://linkedin.com/in/alice" } } } } } } } } }, "example": { "total_jobs": 42, "truncated": true, "company": { "name": "Acme", "domain": "acme.com", "linkedin_url": "https://linkedin.com/company/acme" }, "jobs": [ { "job_title": "Senior Backend Engineer", "job_url": "https://example.com/jobs/1", "job_location": "Paris France", "employment_statuses": [ "full_time" ], "date_posted": "2026-05-30", "description": "Build cool stuff with Rails.", "hiring_team": [ { "name": "Alice Doe", "title": "Engineering Manager", "linkedin_url": "https://linkedin.com/in/alice" } ] } ] } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Missing required company identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Provide at least one of: company_domain, company_name, company_linkedin_url" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key" } } } }, "402": { "description": "Not enough enrichment credits to pay for the lookup. Returned before any job is fetched, and also when a concurrent request drains the balance before this one is charged. Nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable entity. Returned for an invalid filter (each keyword filter must be an array of strings), an invalid country code (use 2-letter ISO 3166-1 alpha-2 codes), or a non-positive or non-integer limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid country code(s): USA. Use 2-letter ISO 3166-1 alpha-2 codes (e.g. US, FR)." } } } }, "429": { "description": "Rate limit exceeded (5 requests per second)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded. Please wait before retrying." } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/company_stack": { "post": { "operationId": "get_company_stack", "tags": [ "Accounts" ], "summary": "Get company technographics stack", "description": "Retrieve a company's technology stack.\n\n**Credits:** 3 credits per request\n\n**Rate limit:** none, credit-spending endpoints are exempt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_domain": { "type": "string", "description": "Company website domain", "example": "notion.so" }, "company_name": { "type": "string", "description": "Company name", "example": "Notion" }, "company_linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn company URL", "example": "https://www.linkedin.com/company/notionhq/" } } }, "examples": { "by_domain": { "summary": "Lookup by domain", "value": { "company_domain": "notion.so" } }, "by_linkedin_url": { "summary": "Lookup by LinkedIn URL", "value": { "company_linkedin_url": "https://www.linkedin.com/company/notionhq/" } }, "by_name": { "summary": "Lookup by name", "value": { "company_name": "Notion" } } } } } }, "responses": { "200": { "description": "Successfully retrieved company stack", "content": { "application/json": { "schema": { "type": "object", "properties": { "technologies": { "type": "array", "description": "List of technology names detected for the company", "items": { "type": "string" } }, "technologies_with_confidence": { "type": "array", "description": "List of technologies with confidence scores", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Technology name" }, "confidence": { "type": "number", "description": "Confidence score returned by provider" } } } } } }, "example": { "technologies": [ "Amazon Web Services", "React", "Segment" ], "technologies_with_confidence": [ { "name": "Amazon Web Services", "confidence": 0.97 }, { "name": "React", "confidence": 0.93 }, { "name": "Segment", "confidence": 0.74 } ] } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Missing required company identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Provide at least one of: company_domain, company_name, company_linkedin_url" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid API key" } } } }, "402": { "description": "Not enough enrichment credits for the 3-credit stack lookup. Returned before the provider is called, so nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "The technology provider rejected the lookup", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "TheirStack API error 422: " } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/accounts/technologies": { "get": { "operationId": "lookup_technology_slug", "tags": [ "Accounts" ], "summary": "Technology slug lookup", "description": "Resolve a technology name to the slugs used by the tech-stack company search endpoints (`POST /intents/accounts/stack` and its preview).", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Technology name to search for.", "example": "hubspot" } ], "responses": { "200": { "description": "Matching technologies", "content": { "application/json": { "schema": { "type": "object", "required": [ "technologies" ], "properties": { "technologies": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "Slug to use in `stacks` / `excluded_stacks`.", "example": "hubspot" }, "name": { "type": "string", "example": "HubSpot" }, "category": { "type": "string", "example": "Marketing Automation" }, "logo": { "type": "string", "format": "uri", "example": "https://cdn.theirstack.com/logos/hubspot.png" }, "description": { "type": "string", "example": "Inbound marketing, sales, and CRM platform." } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "description": "Bad request (query missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unprocessable entity (technology lookup failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/contacts/{id}": { "get": { "operationId": "get_contact_enrichment", "tags": [ "Enrichments" ], "summary": "Get single contact enrichment result", "description": "Retrieves the enrichment result for a single contact by enrichment ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID of the enrichment request to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Enrichment result retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrichment_id": { "type": "string", "format": "uuid", "description": "The ID of the enrichment request" }, "first_name": { "type": "string", "description": "The contact's first name" }, "last_name": { "type": "string", "description": "The contact's last name" }, "status": { "type": "string", "enum": [ "finished", "pending" ], "description": "The status of the enrichment request. `pending` while the waterfall is still running, `finished` once all requested enrichments have completed (regardless of whether data was found)." }, "email": { "type": "string", "format": "email", "description": "The enriched professional email address (present if enrichment_type included email)" }, "email_status": { "type": "string", "description": "The validation status of the professional email (e.g. `deliverable`, `catch-all`, `N/A`)" }, "personal_email": { "type": "string", "format": "email", "description": "The enriched personal email address (present if enrichment_type included personal_email)" }, "personal_email_status": { "type": "string", "description": "The validation status of the personal email (e.g. `valid`, `invalid`, `catch-all`, `N/A`)" }, "phone": { "type": "array", "items": { "type": "string", "description": "Phone number in E.164 format" }, "description": "Array of enriched phone numbers, after the `phone_type` filter is applied (empty array when none found)" }, "phone_details": { "type": "array", "description": "Phone numbers found, each with its line type. Same numbers and order as `phone`, after the `phone_type` filter is applied (empty array when none found).", "items": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number in E.164 format" }, "type": { "type": "string", "enum": [ "mobile", "fixed_or_mobile", "fixed_line", "voip", "toll_free", "premium_rate", "shared_cost", "personal_number", "pager", "uan", "voicemail", "unknown" ], "description": "Line type derived from the number's numbering plan. `fixed_or_mobile` is used in countries where mobile and landline numbers share the same ranges (e.g. the US and Canada); it counts as mobile for the `phone_type` filter and for billing. `unknown` means the number could not be classified." } } } }, "custom": { "type": "object", "description": "Custom fields passed in the request", "additionalProperties": true } } }, "example": { "enrichment_id": "123e4567-e89b-12d3-a456-426614174000", "first_name": "Mathieu", "last_name": "Brun-Picard", "status": "finished", "email": "mathieu@prontohq.com", "email_status": "deliverable", "personal_email": "mathieu.bp@gmail.com", "personal_email_status": "valid", "phone": [ "+12015550123" ], "phone_details": [ { "number": "+12015550123", "type": "fixed_or_mobile" } ], "custom": { "hubspot_id": "4447901" } } } } }, "404": { "description": "Enrichment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Enrichment not found" } } } } } } }, "/contacts/single_enrich": { "post": { "operationId": "enrich_contact_async", "tags": [ "Enrichments" ], "summary": "Enrich a single contact", "description": "Enriches a single contact with specified data points.", "requestBody": { "description": "Contact information for enrichment", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentRequest" }, "example": { "firstname": "Mathieu", "lastname": "Brun-Picard", "domain": "pipecorn.com", "company_name": "Pipecorn", "linkedin_url": "https://www.linkedin.com/in/mathieu-brun-picard/", "webhook_url": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8", "enrichment_type": [ "phone" ], "phone_type": [ "mobile" ], "custom": { "hubspot_id": "4447901" } } } } }, "responses": { "200": { "description": "Enrichment request accepted. The waterfall runs asynchronously: poll the URL in the `Location` header (`GET /contacts/{id}`, using the returned `enrichment_id`) or wait for the `webhook_url` callback to retrieve final results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrichment_id": { "type": "string", "format": "uuid", "description": "The ID of the enrichment request. Use it to poll `GET /contacts/{id}`." }, "first_name": { "type": "string", "description": "The contact's first name" }, "last_name": { "type": "string", "description": "The contact's last name" }, "status": { "type": "string", "enum": [ "pending" ], "description": "Always `pending` on creation; the waterfall runs asynchronously." }, "custom": { "type": "object", "description": "Custom fields passed in the request", "additionalProperties": true }, "status_url": { "type": "string", "format": "uri", "description": "Where to poll the result: `GET /contacts/{id}`. Same value as the `Location` header.", "example": "https://app.pipecorn.com/api/v2/contacts/123e4567-e89b-12d3-a456-426614174000" } } }, "example": { "enrichment_id": "123e4567-e89b-12d3-a456-426614174000", "first_name": "Mathieu", "last_name": "Brun-Picard", "status": "pending", "custom": { "hubspot_id": "4447901" }, "status_url": "https://app.pipecorn.com/api/v2/contacts/123e4567-e89b-12d3-a456-426614174000" } } }, "headers": { "Location": { "description": "Status URL of this enrichment, `GET /contacts/{id}`.", "schema": { "type": "string", "format": "uri" } }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "402": { "description": "Not enough enrichment credits to cover the request. Credits are checked up-front for the whole request, so nothing is enqueued and nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned, and nothing is enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable Entity. Returned when validation fails (e.g. unsupported `enrichment_type` value, missing required identifiers), or when the user has not consented to personal email enrichment but requested `personal_email`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "personal_email_consent_missing": { "summary": "Personal email consent missing", "value": { "error": "You can't use the personal email enrichment feature without consenting with our terms of use" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/contacts/bulk_enrich": { "post": { "operationId": "bulk_enrich_contacts", "tags": [ "Enrichments" ], "summary": "Enrich multiple contacts (deprecated)", "description": "**Deprecated.** Use `POST /contacts/single_enrich` (async, with `webhook_url`) once per contact instead, or the synchronous `POST /contacts/single_enrich` when you need results inline. This endpoint keeps working for existing integrations but receives no new features (such as `phone_type` or `phone_details`).", "requestBody": { "description": "Bulk contact information for enrichment", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contacts" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "Webhook URL to receive enrichment results" }, "phone_country_codes": { "type": "array", "items": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g. \"US\", \"FR\", \"GB\")" }, "description": "Optional. Restrict phone enrichment to phone numbers from these countries (applies to every contact in the batch). When omitted, the user's account-level default phone country codes are applied." } }, "oneOf": [ { "title": "Email batch", "required": [ "enrichment_type", "contacts" ], "properties": { "enrichment_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "email" ] }, "description": "Set to [\"email\"] for the whole batch." }, "contacts": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "firstname", "lastname" ], "properties": { "firstname": { "type": "string", "description": "First name of the contact." }, "lastname": { "type": "string", "description": "Last name of the contact." }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" }, "domain": { "type": "string", "description": "Company domain.", "example": "pipecorn.com" }, "company_name": { "type": "string", "description": "Company name.", "example": "Pipecorn" }, "custom": { "type": "object", "description": "Custom fields to include with the enrichment.", "additionalProperties": true } }, "anyOf": [ { "required": [ "linkedin_url" ] }, { "required": [ "domain" ] }, { "required": [ "company_name" ] } ] } } }, "description": "Each contact requires `firstname`, `lastname`, and one of `linkedin_url`, `domain`, or `company_name`." }, { "title": "Phone batch", "required": [ "enrichment_type", "contacts" ], "properties": { "enrichment_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "phone" ] }, "description": "Set to [\"phone\"] for the whole batch." }, "contacts": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "linkedin_url" ], "properties": { "firstname": { "type": "string", "description": "First name of the contact." }, "lastname": { "type": "string", "description": "Last name of the contact." }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" }, "domain": { "type": "string", "description": "Company domain.", "example": "pipecorn.com" }, "company_name": { "type": "string", "description": "Company name.", "example": "Pipecorn" }, "custom": { "type": "object", "description": "Custom fields to include with the enrichment.", "additionalProperties": true } } } } }, "description": "Each contact requires only `linkedin_url`." }, { "title": "Personal email batch", "required": [ "enrichment_type", "contacts" ], "properties": { "enrichment_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "personal_email" ] }, "description": "Set to [\"personal_email\"] for the whole batch. Requires GDPR consent." }, "contacts": { "type": "array", "maxItems": 100, "items": { "type": "object", "required": [ "linkedin_url" ], "properties": { "firstname": { "type": "string", "description": "First name of the contact." }, "lastname": { "type": "string", "description": "Last name of the contact." }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" }, "domain": { "type": "string", "description": "Company domain.", "example": "pipecorn.com" }, "company_name": { "type": "string", "description": "Company name.", "example": "Pipecorn" }, "custom": { "type": "object", "description": "Custom fields to include with the enrichment.", "additionalProperties": true } } } } }, "description": "Each contact requires `linkedin_url`; the account must have GDPR consent." } ] }, "example": { "contacts": [ { "firstname": "Mathieu", "lastname": "Brun-Picard", "domain": "pipecorn.com", "company_name": "Pipecorn", "linkedin_url": "https://www.linkedin.com/in/mathieu-brun-picard/", "custom": { "hubspot_id": "4447901" } }, { "firstname": "Nicolas", "lastname": "Fernandez-Le Follic", "domain": "pipecorn.com", "company_name": "Pipecorn", "linkedin_url": "https://www.linkedin.com/in/nicolasfernandezlefollic/", "custom": { "hubspot_id": "4447902" } } ], "webhook_url": "https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8", "enrichment_type": [ "email" ] } } } }, "responses": { "200": { "description": "Bulk enrichment request accepted. Each contact is enriched asynchronously; results are delivered via the `webhook_url` callback as each contact finishes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrichment_id": { "type": "string", "format": "uuid", "description": "The ID of the bulk enrichment job" } } }, "example": { "enrichment_id": "123e4567-e89b-12d3-a456-426614174000" } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough enrichment credits to cover the request. Credits are checked up-front for the whole request, so nothing is enqueued and nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned, and nothing is enqueued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable Entity. Returned when validation fails (e.g. unsupported `enrichment_type` value, missing required identifiers), or when the user has not consented to personal email enrichment but requested `personal_email`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "personal_email_consent_missing": { "summary": "Personal email consent missing", "value": { "error": "You can't use the personal email enrichment feature without consenting with our terms of use" } } } } } } }, "deprecated": true, "x-hidden": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/posts": { "post": { "operationId": "extract_posts", "tags": [ "Signals" ], "summary": "Extract posts from a LinkedIn profile or company page", "description": "Returns up to the specified limit of posts for a LinkedIn person profile or company page. The URL is detected automatically: company page URLs use the organization feed; profile URLs use the member profile feed. Results can be narrowed with `posted_within`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_url", "limit" ], "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL (e.g. `/in/...`) or company page URL (e.g. `/company/...`)", "example": "https://www.linkedin.com/in/john-doe" }, "linkedin_profile_url": { "type": "string", "format": "uri", "deprecated": true, "description": "Alias of `linkedin_url`, still accepted. Use `linkedin_url` in new integrations." }, "limit": { "type": "integer", "description": "Maximum number of posts to return", "minimum": 1, "example": 5 }, "posted_within": { "type": "string", "enum": [ "last_24_hours", "last_7_days", "last_30_days" ], "description": "Only include posts published within this window. Omit for no recency filter." } } } } } }, "responses": { "200": { "description": "Successfully extracted posts", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "author": { "type": "string", "description": "Post author name", "example": "Jane Smith" }, "author_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the post author", "example": "https://www.linkedin.com/in/jane-smith" }, "content": { "type": "string", "description": "Post text content", "example": "Post content text..." }, "id": { "type": "string", "description": "Post ID", "example": "1234567890123456789" }, "urn": { "type": "string", "description": "LinkedIn URN for the post", "example": "urn:li:activity:1234567890123456789" }, "base_url": { "type": "string", "format": "uri", "description": "Base post URL", "example": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890123456789" }, "post_url": { "type": "string", "format": "uri", "description": "Full post URL", "example": "https://www.linkedin.com/posts/jane-smith_post-title-activity-1234567890123456789-abcd" }, "published_at": { "type": "string", "format": "date", "description": "Date when the post was published (YYYY-MM-DD)", "example": "2026-03-11" }, "engagement_count": { "type": "integer", "description": "Total engagement on the post (reactions + comments)", "example": 142 }, "reactions_count": { "type": "integer", "description": "Number of reactions on the post", "example": 128 }, "comments_count": { "type": "integer", "description": "Number of comments on the post", "example": 14 } } }, "description": "Posts from the profile or company page, after optional recency filtering" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_limit": { "value": { "error": "Missing required keys: limit" } }, "missing_linkedin_url": { "value": { "error": "Missing required keys: linkedin_url" } }, "invalid_posted_within": { "value": { "error": "Invalid posted_within. Use last_24_hours, last_7_days, last_30_days, or omit the key." } } } } } }, "404": { "description": "LinkedIn profile or company not resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Profile doesn't exist" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/comments": { "post": { "operationId": "extract_comments", "tags": [ "Signals" ], "summary": "Extract comments from a LinkedIn profile", "description": "Extract comments left by a LinkedIn profile on other posts. Uses the voyagerFeedDashProfileUpdates endpoint and paginates until all comments are retrieved or the requested limit is reached.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_url", "limit" ], "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL to extract comments from", "example": "https://www.linkedin.com/in/john-doe" }, "linkedin_profile_url": { "type": "string", "format": "uri", "deprecated": true, "description": "Alias of `linkedin_url`, still accepted. Use `linkedin_url` in new integrations." }, "limit": { "type": "integer", "description": "Maximum number of comments to extract", "minimum": 1, "example": 10 } } } } } }, "responses": { "200": { "description": "Successfully extracted comments", "content": { "application/json": { "schema": { "type": "object", "properties": { "comments": { "type": "array", "description": "Array of comments left by the LinkedIn profile", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric activity ID extracted from the URN", "example": "1234567890123456789" }, "comment_url": { "type": "string", "format": "uri", "description": "Full LinkedIn URL with commentUrn query parameter linking directly to the comment", "example": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890123456789?commentUrn=urn%3Ali%3Acomment%3A%28urn%3Ali%3Aactivity%3A1234567890123456789%2C9876543210987654321%29" }, "author": { "type": "string", "description": "Full name of the commenter", "example": "John Doe" }, "author_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the commenter", "example": "https://www.linkedin.com/in/john-doe" }, "comment_text": { "type": "string", "description": "Text content of the comment", "example": "Great point - we've been seeing the same pattern." }, "commented_at": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the comment was posted", "example": "2026-03-11T14:17:00Z" }, "urn": { "type": "string", "description": "LinkedIn URN identifying the comment", "example": "urn:li:comment:(urn:li:activity:1234567890123456789,9876543210987654321)" } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_required": { "value": { "error": "Missing required keys: linkedin_url, limit" } } } } } }, "404": { "description": "LinkedIn profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Couldn't find resource on LinkedIn. Please make sure it exists and that you have the right permissions to access it." } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/reactions": { "post": { "operationId": "extract_reactions", "tags": [ "Signals" ], "summary": "Extract reactions from a LinkedIn profile", "description": "Extract reactions left by a LinkedIn profile on other posts. Paginates through the profile's feed activity and filters for reaction-type elements, returning up to the specified limit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_url", "limit" ], "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL to extract reactions from", "example": "https://www.linkedin.com/in/john-doe" }, "linkedin_profile_url": { "type": "string", "format": "uri", "deprecated": true, "description": "Alias of `linkedin_url`, still accepted. Use `linkedin_url` in new integrations." }, "limit": { "type": "integer", "description": "Maximum number of reactions to extract", "minimum": 1, "example": 10 } } } } } }, "responses": { "200": { "description": "Successfully extracted reactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "reactions": { "type": "array", "description": "Array of reactions left by the LinkedIn profile on other posts", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric activity ID extracted from the URN", "example": "1234567890123456789" }, "reaction_type": { "type": "string", "enum": [ "LIKE", "CELEBRATE", "INSIGHTFUL", "FUNNY", "SUPPORT", "LOVE" ], "description": "Type of LinkedIn reaction", "example": "CELEBRATE" }, "post_url": { "type": "string", "format": "uri", "description": "Full LinkedIn URL of the post that was reacted to", "example": "https://www.linkedin.com/posts/jane-smith_post-title-activity-1234567890123456789-abcd" }, "author": { "type": "string", "description": "Full name of the post author", "example": "Jane Smith" }, "author_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the post author (tracking params stripped)", "example": "https://www.linkedin.com/in/jane-smith" }, "reacted_at": { "type": "string", "format": "date", "description": "Date when the reaction was made (YYYY-MM-DD)", "example": "2026-03-11" }, "urn": { "type": "string", "description": "LinkedIn URN identifying the activity", "example": "urn:li:activity:1234567890123456789" } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_required": { "value": { "error": "Missing required keys: linkedin_url, limit" } } } } } }, "404": { "description": "LinkedIn profile not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Couldn't find resource on LinkedIn. Please make sure it exists and that you have the right permissions to access it." } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/posts_engagers": { "post": { "operationId": "extract_post_engagers", "tags": [ "Signals" ], "summary": "Extract post engagers", "description": "Start an asynchronous extraction of leads that engaged with a LinkedIn post.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "post_url", "webhook_url", "engagement_type" ], "properties": { "post_url": { "type": "string", "format": "uri", "description": "Valid LinkedIn post URL (use the link from the \"share\" button)", "example": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890123456789" }, "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive the extracted engagers when the job completes", "example": "https://your-company.com/webhooks/post-engagers" }, "engagement_type": { "type": "string", "enum": [ "reactions", "comments", "all" ], "description": "Which engagements to extract: reactions only, comments only, or all", "example": "all" }, "persona": { "type": "string", "format": "uuid", "description": "Optional persona UUID to filter engagers", "example": "550e8400-e29b-41d4-a716-446655440000" }, "lead_list_name": { "type": "string", "description": "Custom name for the search (defaults to \"Social Post Tracking - \")", "example": "Q1 campaign post engagers" }, "company_size": { "type": "array", "items": { "type": "string" }, "description": "Optional company size filters for engagers" }, "exclude_people_from_same_company": { "type": "boolean", "description": "Whether to exclude engagers from the same company as the post author", "example": false } } } } } }, "responses": { "201": { "description": "Post engagement extraction started; results will be sent to the webhook", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "properties": { "message": { "type": "string", "example": "Post engagement extraction will begin shortly." }, "search_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the search", "example": "550e8400-e29b-41d4-a716-446655440000" }, "post_url": { "type": "string", "format": "uri", "description": "The post URL being tracked" }, "expected_profiles_count": { "type": "integer", "description": "Number of profiles that will be extracted and sent to the webhook", "example": 150 } } } } }, "example": { "message": { "message": "Post engagement extraction will begin shortly.", "search_id": "550e8400-e29b-41d4-a716-446655440000", "post_url": "https://www.linkedin.com/posts/activity-7123456789012345678", "expected_profiles_count": 150 } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request (missing required keys, invalid post URL, or invalid engagement_type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_keys": { "value": { "error": "Missing required keys: post_url, webhook_url, engagement_type" } }, "invalid_post_url": { "value": { "error": "Valid LinkedIn post URL is required. Use the link obtained after clicking on \"share\" button" } }, "invalid_engagement_type": { "value": { "error": "Invalid engagement_type. Must be one of: reactions, comments, all" } } } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable (persona not found, post ID not found, or plan limit reached)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "persona_not_found": { "value": { "error": "Persona not found" } }, "post_id_not_found": { "value": { "error": "Post ID not found" } }, "plan_limit": { "value": { "error": "Can't proceed with the request. Plan limit reached." } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/accounts/hiring": { "post": { "operationId": "create_hiring_intent", "tags": [ "Signals" ], "summary": "Create hiring intent for accounts", "description": "Start a company hiring-intent search based on job posting activity. Only documented fields are allowed; unknown keys return 422.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive hiring intent notifications", "example": "https://your-company.com/webhooks/hiring" }, "streaming": { "type": "boolean", "description": "Whether to stream results to the webhook as they are processed", "example": false }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of companies to return", "example": 100 }, "published_date": { "type": "string", "description": "Relative publish-date filter for jobs", "enum": [ "last_24_hours", "last_7_days", "last_15_days", "last_30_days", "last_90_days", "last_180_days", "last_360_days" ], "example": "last_30_days" }, "exclude_consulting_recruiting": { "type": "boolean", "description": "Exclude consulting and recruiting job postings", "example": true }, "exclude_internships": { "type": "boolean", "description": "Exclude internship job postings", "example": true }, "company_size": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn-style company size ranges (en-dashes are normalized to hyphens server-side)", "example": [ "51-200", "201-500" ] }, "selected_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to match in job postings", "example": [ "sales", "account executive" ] }, "excluded_keywords": { "type": "array", "items": { "type": "string" }, "description": "Keywords to exclude from job postings", "example": [ "intern", "junior" ] }, "selected_titles": { "type": "array", "items": { "type": "string" }, "description": "Job titles to include", "example": [ "Account Executive", "Sales Development Representative" ] }, "excluded_titles": { "type": "array", "items": { "type": "string" }, "description": "Job titles to exclude", "example": [ "Intern", "Manager" ] }, "included_locations": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to include", "example": [ 103644278 ] }, "excluded_locations": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to exclude", "example": [ 101282230 ] }, "included_industries": { "type": "array", "items": { "type": "string" }, "description": "Industry IDs to include", "example": [ "4" ] } } } } } }, "responses": { "200": { "description": "No matching companies; no import created", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_count", "total_available", "message" ], "properties": { "total_count": { "type": "integer", "example": 0 }, "total_available": { "type": "integer", "example": 0 }, "message": { "type": "string", "example": "No results found" } } } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "201": { "description": "Hiring intent search started successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "required": [ "total_count", "total_available", "message", "id" ], "properties": { "total_count": { "type": "integer", "description": "Companies that will be imported (capped by `limit`).", "example": 42 }, "total_available": { "type": "integer", "description": "Full match count.", "example": 128 }, "message": { "type": "string", "example": "Hiring intent search started successfully. You will receive the results on your webhook shortly." }, "id": { "type": "string", "format": "uuid", "description": "Import job UUID", "example": "5d4fabd2-e26d-47d1-b0de-4bf370f7b799" } } } } }, "example": { "message": { "total_count": 42, "total_available": 128, "message": "Hiring intent search started successfully. You will receive the results on your webhook shortly.", "id": "5d4fabd2-e26d-47d1-b0de-4bf370f7b799" } } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough enrichment credits for the companies that would be imported (3 credits per company). No import is created and nothing is spent. The message reports the shortfall.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits. You need 30 credits but only have 5 available.", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned, and no import is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable entity (invalid published_date, unknown parameters, or invalid optional filters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/accounts/growth": { "post": { "operationId": "create_growth_intent", "tags": [ "Signals" ], "summary": "Create growth intent for accounts", "description": "Start a LinkedIn account (company) search by growth criteria. Only documented fields are allowed; unknown keys return 422.\n\n**Valid criteria (choose one mode):**\n1. **Company-wide headcount growth:** Provide at least one of `min_headcount_growth_percentage` or `max_headcount_growth_percentage`. Do not send `department` in this mode.\n2. **Department metrics:** Send `department` (LinkedIn function ID as a string, e.g. `\"1\"`) plus at least one of `min_department_headcount`, `max_department_headcount`, `min_department_headcount_growth_percentage`, or `max_department_headcount_growth_percentage`.\n\nDepartment fields cannot be combined with company-wide headcount growth fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive growth intent results when processing completes", "example": "https://your-company.com/webhooks/growth" }, "streaming": { "type": "boolean", "description": "Whether to stream results to the webhook as they are processed", "example": false }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of companies to import. If omitted, import volume is capped at 1000 even when the search finds more; response `total` reflects the effective count", "example": 500 }, "min_headcount_growth_percentage": { "type": "number", "description": "Minimum company-wide headcount growth percentage (use with or without `max_headcount_growth_percentage`; not valid together with `department`)", "example": 10 }, "max_headcount_growth_percentage": { "type": "number", "description": "Maximum company-wide headcount growth percentage (use with or without `min_headcount_growth_percentage`; not valid together with `department`)", "example": 50 }, "department": { "type": "string", "description": "LinkedIn function ID to target (string, e.g. `\"1\"`). Required when using any department headcount or department growth field; must not be set together with company-wide headcount growth fields", "example": "1" }, "min_department_headcount": { "type": "integer", "description": "Minimum headcount in the selected department (requires `department`)", "example": 5 }, "max_department_headcount": { "type": "integer", "description": "Maximum headcount in the selected department (requires `department`)", "example": 100 }, "min_department_headcount_growth_percentage": { "type": "number", "description": "Minimum department headcount growth percentage (requires `department`)", "example": 15 }, "max_department_headcount_growth_percentage": { "type": "number", "description": "Maximum department headcount growth percentage (requires `department`)", "example": 80 }, "company_size": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn-style company size range strings (e.g. `51-200`). Unicode en-dashes in values are normalized to hyphens on the server", "example": [ "51-200", "201-500" ] }, "included_locations": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to include", "example": [ 103644278 ] }, "excluded_locations": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to exclude", "example": [] }, "included_industries": { "type": "array", "items": { "type": "string" }, "description": "Industry IDs to include", "example": [ "4" ] } } } } } }, "responses": { "201": { "description": "Search started; results are delivered to the webhook", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "id", "total", "preview" ], "properties": { "message": { "type": "string", "description": "Confirmation that the account search started", "example": "Account search started successfully. You will receive the results on your webhook shortly." }, "id": { "type": "string", "format": "uuid", "description": "UUID of the import job", "example": "5d4fabd2-e26d-47d1-b0de-4bf370f7b799" }, "total": { "type": "integer", "description": "Number of companies for this run: if `limit` is set, the lesser of search size and `limit`; otherwise the full search size (import may still cap at 1000)", "example": 150 }, "preview": { "type": "array", "maxItems": 10, "description": "Up to 10 sample companies from the search", "items": { "type": "object", "properties": { "company_name": { "type": "string", "example": "Acme Inc" }, "industry": { "type": "string", "example": "Software Development" }, "linkedin_id": { "type": "string", "description": "Numeric company ID extracted from the result", "example": "123456" }, "linkedin_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/company/123456" } } } }, "account_url": { "type": "string", "format": "uri", "description": "Present only in development environments (debugging)" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (invalid API key, insufficient credits to create a list for the result size, or Sales Navigator requirements not met)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable entity (invalid growth parameter combinations, unknown parameters, invalid `department`, or invalid optional filters)", "content": { "application/json": { "schema": { "type": "object", "description": "Error payload shape varies; may include `error`, `message`, `unauthorized_params`, `valid_combinations`, `valid_departments`, etc." } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/accounts/lookalikes": { "post": { "operationId": "find_lookalike_companies", "tags": [ "Signals" ], "summary": "Find company lookalikes", "description": "Find companies that look like your target accounts. Provide one or more LinkedIn company URLs; the API uses them to generate a lookalike search and streams results to your webhook. Location IDs can be retrieved using the Location IDs endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive lookalike results", "example": "https://your-company.com/webhooks/lookalikes" }, "company_linkedin_url": { "type": "string", "format": "uri", "description": "Single LinkedIn company URL to use as reference (use this or company_linkedin_urls)", "example": "https://www.linkedin.com/company/acme-corp" }, "company_linkedin_urls": { "type": "array", "items": { "type": "string", "format": "uri" }, "description": "LinkedIn company URLs to use as reference, up to 3 used for LLM keyword generation (use this or company_linkedin_url)", "example": [ "https://www.linkedin.com/company/acme-corp", "https://www.linkedin.com/company/example-inc" ] }, "streaming": { "type": "boolean", "description": "Whether to stream results to the webhook as they are found", "example": false }, "limit": { "type": "integer", "description": "Maximum number of companies to return", "minimum": 1, "example": 100 }, "company_size": { "type": "array", "items": { "type": "string" }, "description": "Company size range filters (e.g. headcount bands)", "example": [ "51-200", "201-500" ] }, "included_locations": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to include (use Location IDs endpoint to resolve names)", "example": [ 103644278 ] }, "excluded_locations": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to exclude", "example": [] } } } } } }, "responses": { "201": { "description": "Lookalike search started; results will be sent to the webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message", "example": "Lookalike search started successfully. You will receive the results on your webhook shortly." }, "id": { "type": "string", "description": "Unique identifier for the import/search", "example": "550e8400-e29b-41d4-a716-446655440000" }, "total": { "type": "integer", "description": "Total number of companies that will be processed", "example": 100 }, "preview": { "type": "array", "description": "First 10 matching companies as a preview", "items": { "type": "object", "properties": { "company_name": { "type": "string", "example": "Acme Corp" }, "industry": { "type": "string", "example": "Software Development" }, "linkedin_id": { "type": "string", "description": "LinkedIn company numeric ID", "example": "12345" }, "linkedin_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/company/12345" } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request (e.g. missing company URL, invalid URLs, or processing error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_url": { "value": { "error": "Either company_linkedin_url or company_linkedin_urls is required in your payload" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/find_new_hires": { "post": { "operationId": "find_new_hires", "tags": [ "Signals" ], "summary": "Find new hires", "description": "Find people who recently changed jobs and match your ICP", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive new hire notifications", "example": "https://your-company.com/webhooks/new_hires" }, "persona_id": { "type": "string", "description": "Persona ID to target specific roles", "example": "persona_abc123" }, "headcount": { "type": "array", "items": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G", "H", "I" ] }, "description": "Company headcount range filters", "example": [ "C", "D", "E" ] }, "industries": { "type": "array", "items": { "type": "string" }, "description": "Industry filters", "example": [ "Software Development" ] }, "location_ids": { "type": "array", "items": { "type": "integer" }, "description": "Location IDs to filter by", "example": [ 103644278 ] }, "domain_allow_list": { "type": "array", "items": { "type": "string" }, "description": "Only include companies from these domains", "example": [ "acme.com" ] }, "domain_deny_list": { "type": "array", "items": { "type": "string" }, "description": "Exclude companies from these domains", "example": [ "competitor.com" ] } } } } } }, "responses": { "201": { "description": "New hires tracking created", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "New hires tracking created successfully. Next run will be in 24 hours." } } }, "example": { "message": "New hires tracking created successfully. Next run will be in 24 hours." } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/track_job_changes": { "post": { "operationId": "track_job_changes", "tags": [ "Signals" ], "summary": "Track job changes", "description": "Track job changes for a list of contacts. Each contact is identified by its LinkedIn URL, or by its first name, last name and current company. Contacts are matched in the background; the first check runs once matching is done, then every month. Contacts who changed company or were promoted are sent to your webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url", "contacts" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "URL to receive job change notifications", "example": "https://your-company.com/webhooks/job_changes" }, "contacts": { "type": "array", "minItems": 1, "maxItems": 10000, "description": "Contacts to track, up to 10,000 per request. Each contact needs either `linkedin_url`, or all of `first_name`, `last_name` and `company_name`.", "items": { "type": "object", "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/john-doe" }, "first_name": { "type": "string", "description": "First name of the contact. Required with `last_name` and `company_name` when `linkedin_url` is not provided.", "example": "Jane" }, "last_name": { "type": "string", "description": "Last name of the contact. Required with `first_name` and `company_name` when `linkedin_url` is not provided.", "example": "Smith" }, "company_name": { "type": "string", "description": "Current company of the contact. Required with `first_name` and `last_name` when `linkedin_url` is not provided.", "example": "Acme" } } }, "example": [ { "linkedin_url": "https://www.linkedin.com/in/john-doe" }, { "first_name": "Jane", "last_name": "Smith", "company_name": "Acme" } ] } } } } } }, "responses": { "201": { "description": "Job change tracking created", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "example": "Job changes tracking created successfully. Contacts are being matched; the initial check runs once matching is done, then every 30 days." } } }, "example": { "message": "Job changes tracking created successfully. Contacts are being matched; the initial check runs once matching is done, then every 30 days." } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request (missing required keys, unidentifiable contact, too many contacts, alert limit reached, or tracking creation failed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_contacts": { "value": { "error": "Missing required keys: contacts" } }, "missing_webhook_url": { "value": { "error": "webhook_url key is required in your payload" } }, "empty_contacts": { "value": { "error": "Contacts are required. Please provide at least one contact to track job changes." } }, "unidentifiable_contact": { "value": { "error": "Either first_name, last_name and company_name or linkedin_url must be provided" } }, "too_many_contacts": { "value": { "error": "You can track up to 10000 contacts per request." } }, "alert_limit": { "value": { "error": "You have reached the maximum number of alerts in your plan. Reach out to support if you need more alerts." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/connections": { "post": { "operationId": "find_connections", "tags": [ "Signals" ], "summary": "Find who can introduce you to a LinkedIn lead", "description": "Returns your 1st-degree connections who can introduce you to a target lead, via LinkedIn Sales Navigator. Each connection comes with the paths that link it to the target, the companies both worked at (overlap, location, headcount) and a relationship strength. Connections are sorted strongest first. Requires a connected LinkedIn account with Sales Navigator access.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_url" ], "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the target person. Accepts public profile URLs (`/in/...`), Sales Navigator URLs (`/sales/lead/...`), or internal LinkedIn URNs.", "example": "https://www.linkedin.com/in/john-doe" }, "linkedin_profile_url": { "type": "string", "format": "uri", "deprecated": true, "description": "Alias of `linkedin_url`, still accepted. Use `linkedin_url` in new integrations." }, "spotlights": { "type": "array", "items": { "type": "string", "enum": [ "SHARED_CONNECTION", "SHARED_EXPERIENCE", "SHARED_EDUCATION", "SHARED_GROUP" ] }, "minItems": 1, "default": [ "SHARED_CONNECTION" ], "description": "Optional. Kinds of warm path to look for. `SHARED_CONNECTION`: your connection is connected to the target. `SHARED_EXPERIENCE`: they worked at the same company. `SHARED_EDUCATION`: same school. `SHARED_GROUP`: same LinkedIn group. Each kind runs one more Sales Navigator lookup. TeamLink is not supported.", "example": [ "SHARED_CONNECTION", "SHARED_EXPERIENCE" ] } } } } } }, "responses": { "200": { "description": "Connections found successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "description": "Number of warm paths found across the requested spotlights. A connection reached through two spotlights counts twice.", "example": 3 }, "connections": { "type": "array", "description": "Your 1st-degree connections who can introduce you to the target, strongest relationship first. A person found through several spotlights appears once.", "items": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name of the connection", "example": "Jane" }, "last_name": { "type": "string", "description": "Last name of the connection", "example": "Doe" }, "full_name": { "type": "string", "description": "Full name of the connection", "example": "Jane Doe" }, "degree": { "type": "integer", "description": "LinkedIn connection degree with the authenticated user (always 1)", "example": 1 }, "profile_urn": { "type": "string", "description": "LinkedIn Sales Navigator profile URN", "example": "urn:li:fs_salesProfile:(ACwAABD5FBQ,NAME_SEARCH,vIqI)" }, "sales_navigator_url": { "type": "string", "format": "uri", "description": "URL to the connection's Sales Navigator profile", "example": "https://www.linkedin.com/sales/lead/ACwAABD5FBQ,NAME_SEARCH,vIqI/" }, "linkedin_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL to the connection's public LinkedIn profile (null if not available)", "example": "https://www.linkedin.com/in/jane-doe/" }, "profile_picture_url": { "type": "string", "format": "uri", "nullable": true, "description": "URL to the connection's profile picture (null if not available)", "example": "https://media.licdn.com/dms/image/..." }, "current_position": { "type": "object", "nullable": true, "description": "Current job position of the connection", "properties": { "title": { "type": "string", "nullable": true, "description": "Current job title", "example": "VP Sales" }, "company": { "type": "string", "nullable": true, "description": "Current company name", "example": "Acme Corp" } } }, "paths": { "type": "array", "description": "How this connection is linked to the target, one entry per spotlight it was found through.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SHARED_CONNECTION", "SHARED_EXPERIENCE", "SHARED_EDUCATION", "SHARED_GROUP" ], "description": "Spotlight that found this path.", "example": "SHARED_CONNECTION" }, "reason": { "type": "string", "nullable": true, "description": "LinkedIn's explanation of the path, when it gives one.", "example": "You both know Ada Lovelace" } } } }, "shared_experiences": { "type": "array", "description": "Every company both the connection and the target worked at, read from their LinkedIn positions. Empty when they never worked at the same company.", "items": { "type": "object", "properties": { "company_id": { "type": "string", "description": "LinkedIn company id.", "example": "1035" }, "company": { "type": "string", "description": "Company name.", "example": "Sellsy" }, "overlap_months": { "type": "integer", "nullable": true, "description": "Months both were at the company at the same time. `0` means they worked there at different times. `null` when a start date is missing.", "example": 18 }, "approximate_dates": { "type": "boolean", "description": "`true` when a position only gives years: the overlap then counts each year as a whole and can be overstated.", "example": false }, "same_location": { "type": "boolean", "nullable": true, "description": "Whether both positions list the same city. `null` when one of them has no location.", "example": true }, "company_size": { "type": "integer", "nullable": true, "description": "The company's headcount today, as reported by LinkedIn. `null` when unknown.", "example": 45 } } } }, "relationship_strength": { "type": "object", "description": "How likely the connection is to know the target well. See [relationship strength](/api-reference/endpoints/signals/connections#relationship-strength).", "properties": { "score": { "type": "integer", "description": "Higher means a stronger tie.", "example": 7 }, "level": { "type": "string", "enum": [ "strong", "medium", "weak" ], "description": "`strong` from 4, `medium` from 2, `weak` below.", "example": "strong" } } } } } }, "totals_by_spotlight": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Number of warm paths found per requested spotlight.", "example": { "SHARED_CONNECTION": 3, "SHARED_EXPERIENCE": 1 } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request — missing required `linkedin_url`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_keys": { "value": { "error": "Missing required keys: linkedin_url" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable — invalid spotlights, LinkedIn account not connected or Sales Navigator credentials expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_spotlights": { "value": { "error": "spotlights must be a non-empty array of: SHARED_CONNECTION, SHARED_EXPERIENCE, SHARED_EDUCATION, SHARED_GROUP" } }, "no_linkedin_credentials": { "value": { "error": "LinkedIn credentials not found. Please connect your LinkedIn account." } }, "no_sales_nav": { "value": { "error": "Sales Navigator credentials expired. Refresh your connection on Pipecorn interface, or set parameter 'live' to false in your request body" } } } } } }, "429": { "description": "Rate limit exceeded (your plan's per-minute limit), or rate limited by LinkedIn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/accounts/stack/preview": { "post": { "operationId": "preview_accounts_by_stack", "tags": [ "Signals" ], "summary": "Preview companies by tech stack", "description": "Return the total number of companies matching a technology-stack query plus a blurred sample. Free — spends no credits. Only documented fields are allowed; unknown keys return 422.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stacks" ], "properties": { "stacks": { "type": "array", "items": { "type": "string" }, "description": "Technology slugs to match. Resolve names to slugs with GET /accounts/technologies.", "example": [ "shopify", "webflow" ] }, "stack_match": { "type": "string", "enum": [ "or", "and" ], "default": "or", "description": "How `stacks` combine. `or` matches companies using any listed technology; `and` requires all of them.", "example": "or" }, "excluded_stacks": { "type": "array", "items": { "type": "string" }, "description": "Technology slugs to exclude.", "example": [ "wordpress" ] }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO country codes, OR-matched against the company's country.", "example": [ "US", "FR" ] }, "included_industries": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn industry IDs to include, OR-matched.", "example": [ "2190", "34" ] }, "excluded_industries": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn industry IDs to exclude.", "example": [ "27" ] }, "company_size": { "type": "array", "items": { "type": "string", "enum": [ "Self-employed", "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "description": "Company size display buckets to include.", "example": [ "11-50", "51-200" ] } } } } } }, "responses": { "200": { "description": "Preview count and blurred company sample", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_count", "preview" ], "properties": { "total_count": { "type": "integer", "description": "Exact number of matching companies.", "example": 428 }, "preview": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Acme" }, "domain": { "type": "string", "example": "acme.com" }, "website": { "type": "string", "example": "https://acme.com" }, "industry": { "type": "string", "example": "Software Development" }, "location": { "type": "string", "example": "Paris France" }, "city": { "type": "string", "example": "Paris" }, "country": { "type": "string", "example": "France" }, "linkedin_url": { "type": "string", "example": "https://linkedin.com/company/acme" }, "technologies_found": { "type": "array", "items": { "type": "object", "properties": { "technology_name": { "type": "string", "example": "Shopify" }, "confidence": { "type": "string", "example": "high" }, "job_mentions": { "type": "integer", "example": 3 } } } } } }, "description": "Sample of matching companies (up to 25). Company identifiers may be blurred; the count is exact." } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request (stacks missing or empty)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable entity (invalid filters or unknown parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/accounts/stack": { "post": { "operationId": "search_accounts_by_stack", "tags": [ "Signals" ], "summary": "Find companies by tech stack", "description": "Start an async import of companies matching a technology-stack query. Results are delivered to `webhook_url`. Spends 3 enrichment credits per imported company. Only documented fields are allowed; unknown keys return 422.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "stacks", "webhook_url" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "URL that receives the imported company records.", "example": "https://your-company.com/webhooks/stack" }, "stacks": { "type": "array", "items": { "type": "string" }, "description": "Technology slugs to match. Resolve names to slugs with GET /accounts/technologies.", "example": [ "shopify", "webflow" ] }, "stack_match": { "type": "string", "enum": [ "or", "and" ], "default": "or", "description": "How `stacks` combine. `or` matches companies using any listed technology; `and` requires all of them.", "example": "or" }, "excluded_stacks": { "type": "array", "items": { "type": "string" }, "description": "Technology slugs to exclude.", "example": [ "wordpress" ] }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO country codes, OR-matched against the company's country.", "example": [ "US", "FR" ] }, "included_industries": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn industry IDs to include, OR-matched.", "example": [ "2190", "34" ] }, "excluded_industries": { "type": "array", "items": { "type": "string" }, "description": "LinkedIn industry IDs to exclude.", "example": [ "27" ] }, "company_size": { "type": "array", "items": { "type": "string", "enum": [ "Self-employed", "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "description": "Company size display buckets to include.", "example": [ "11-50", "51-200" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1000, "description": "Caps how many companies are imported (and billed). Defaults to 1000, which is also the hard ceiling.", "example": 200 }, "streaming": { "type": "boolean", "description": "When true, companies are POSTed to the webhook one at a time instead of in a single payload.", "example": false }, "name": { "type": "string", "description": "Optional import name.", "example": "Shopify prospects" } } } } } }, "responses": { "200": { "description": "No matching companies; no import created", "content": { "application/json": { "schema": { "type": "object", "required": [ "total_count", "total_available", "message" ], "properties": { "total_count": { "type": "integer", "example": 0 }, "total_available": { "type": "integer", "example": 0 }, "message": { "type": "string", "example": "No results found" } } } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "201": { "description": "Stack intent search started successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "object", "required": [ "total_count", "total_available", "message", "id" ], "properties": { "total_count": { "type": "integer", "description": "Companies that will be imported (capped by `limit`, then the 1000 ceiling).", "example": 200 }, "total_available": { "type": "integer", "description": "Full match count.", "example": 428 }, "message": { "type": "string", "example": "Stack intent search started successfully. You will receive the results on your webhook shortly." }, "id": { "type": "string", "format": "uuid", "description": "Import job UUID.", "example": "b3f1c2d4-0000-0000-0000-000000000000" } } } } }, "example": { "message": { "total_count": 200, "total_available": 428, "message": "Stack intent search started successfully. You will receive the results on your webhook shortly.", "id": "b3f1c2d4-0000-0000-0000-000000000000" } } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request (stacks or webhook_url missing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized (missing or invalid API key)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Not enough enrichment credits for the companies that would be imported (3 credits per company). No import is created and nothing is spent. The message reports the shortfall.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits. You need 30 credits but only have 5 available.", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned, and no import is created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Unprocessable entity (invalid filters or unknown parameters)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/leads/warm_intros": { "post": { "operationId": "find_lead_warm_intros", "tags": [ "Signals" ], "summary": "Find warm intros to a LinkedIn profile", "description": "Finds, for one of your 1st-degree LinkedIn connections, the people connected to them (1st, 2nd or 3rd degree from you) who worked at one of the target's past companies — the colleagues most likely to introduce you. Optionally narrowed to a persona or to job titles. Runs a live LinkedIn Sales Navigator search and returns the results synchronously.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_url" ], "properties": { "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the person you want an intro to. Must be one of your 1st-degree connections. Accepts public profile URLs (`/in/...`), Sales Navigator URLs (`/sales/lead/...`), or internal LinkedIn URNs.", "example": "https://www.linkedin.com/in/john-doe" }, "linkedin_profile_url": { "type": "string", "format": "uri", "deprecated": true, "description": "Alias of `linkedin_url`, still accepted. Use `linkedin_url` in new integrations." }, "persona_id": { "type": "string", "format": "uuid", "description": "Optional. Id of one of your personas (see `GET /personas`). Its job titles, locations, industries and company sizes are added to the search. Cannot be combined with `job_titles` or `excluded_job_titles`.", "example": "8f2c1b7e-3a4d-4e5f-9a6b-1c2d3e4f5a6b" }, "job_titles": { "type": "array", "items": { "type": "string" }, "description": "Optional. Keep only people whose current title matches one of these. Use it instead of `persona_id`.", "example": [ "Head of Sales", "VP Sales" ] }, "excluded_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Optional. Drop people whose current title matches one of these. Requires `job_titles`.", "example": [ "Intern" ] }, "target_company_ids": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "Optional. LinkedIn company ids (numeric). Keep only the people who work at one of these companies today, e.g. the accounts in your open pipeline.", "example": [ "1441", "1035" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of leads to return.", "example": 25 } } } } } }, "responses": { "200": { "description": "Warm intro search completed", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Total number of matching people on Sales Navigator. Can exceed the number of `leads` returned.", "example": 12 }, "past_companies": { "type": "array", "description": "The target's past companies used as the past-company filter: every company of an ended position, except the company the target works at today. Empty when the target has none, in which case no search is run and `leads` is empty.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "LinkedIn company id", "example": "1035" }, "name": { "type": "string", "description": "Company name as shown on the target's profile", "example": "BNP Paribas" } } } }, "leads": { "type": "array", "description": "People connected to the target who previously worked at one of `past_companies`", "items": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "full_name": { "type": "string", "example": "Jane Doe" }, "headline": { "type": "string", "nullable": true, "example": "VP Sales at Acme Corp" }, "degree": { "type": "integer", "description": "Connection degree between you and the lead (1, 2 or 3)", "example": 2 }, "current_title": { "type": "string", "nullable": true, "example": "VP Sales" }, "current_company": { "type": "string", "nullable": true, "example": "Acme Corp" }, "linkedin_id": { "type": "string", "description": "LinkedIn Sales Navigator member id", "example": "ACwAABD5FBQ" }, "sales_navigator_url": { "type": "string", "format": "uri", "example": "https://www.linkedin.com/sales/lead/ACwAABD5FBQ,NAME_SEARCH,vIqI/" } } } } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request — missing `linkedin_url`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_keys": { "value": { "error": "Missing required keys: linkedin_url" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The profile or the persona was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "profile_not_found": { "value": { "error": "Profile doesn't exist" } }, "persona_not_found": { "value": { "error": "Persona not found" } } } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Invalid parameters, the profile is not one of your 1st-degree connections, LinkedIn account not connected, or Sales Navigator not connected / expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_limit": { "value": { "error": "limit must be an integer between 1 and 100" } }, "persona_and_titles": { "value": { "error": "persona_id cannot be combined with job_titles or excluded_job_titles" } }, "excluded_without_titles": { "value": { "error": "excluded_job_titles requires job_titles" } }, "invalid_target_companies": { "value": { "error": "target_company_ids must be an array of at most 100 LinkedIn company ids" } }, "not_connected": { "value": { "error": "You are not connected to this profile on LinkedIn. Warm intros only work for your 1st-degree connections." } }, "no_linkedin_credentials": { "value": { "error": "LinkedIn credentials not found. Please connect your LinkedIn account." } }, "no_sales_nav": { "value": { "error": "Sales Navigator credentials expired. Refresh your connection on Pipecorn interface, or set parameter 'live' to false in your request body" } } } } } }, "429": { "description": "Rate limit exceeded (1 request per second per user, or your plan's per-minute limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/intents/accounts/warm_intros": { "post": { "operationId": "find_account_warm_intros", "tags": [ "Signals" ], "summary": "Find warm intros into an account", "description": "Finds the decision makers of a company in your 2nd-degree network, then who among your 1st-degree connections can introduce you to each of them, with the same paths, shared experiences and relationship strength as `POST /intents/leads/connections`. Runs in the background and posts the result to `webhook_url`. Requires a connected LinkedIn account with Sales Navigator access. Doesn't consume credits.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "company_linkedin_id", "webhook_url" ], "properties": { "company_linkedin_id": { "type": "string", "pattern": "^\\d+$", "description": "Numeric LinkedIn company id of the account (the `linkedin_id` returned by `POST /accounts/single_enrich`). A number is accepted too.", "example": "1441" }, "persona_id": { "type": "string", "format": "uuid", "description": "Optional. Id of one of your personas (see `GET /personas`). Its job titles, locations, industries and company sizes select the decision makers. Cannot be combined with `job_titles` or `excluded_job_titles`.", "example": "8f2c1b7e-3a4d-4e5f-9a6b-1c2d3e4f5a6b" }, "job_titles": { "type": "array", "items": { "type": "string" }, "description": "Optional. Keep only decision makers whose current title matches one of these. Use it instead of `persona_id`.", "example": [ "CFO", "VP Finance" ] }, "excluded_job_titles": { "type": "array", "items": { "type": "string" }, "description": "Optional. Drop people whose current title matches one of these. Requires `job_titles`.", "example": [ "Intern" ] }, "spotlights": { "type": "array", "items": { "type": "string", "enum": [ "SHARED_CONNECTION", "SHARED_EXPERIENCE", "SHARED_EDUCATION", "SHARED_GROUP" ] }, "minItems": 1, "default": [ "SHARED_CONNECTION" ], "description": "Optional. Kinds of warm path to look for. `SHARED_CONNECTION`: your connection is connected to the target. `SHARED_EXPERIENCE`: they worked at the same company. `SHARED_EDUCATION`: same school. `SHARED_GROUP`: same LinkedIn group. Each kind runs one more Sales Navigator lookup. TeamLink is not supported.", "example": [ "SHARED_CONNECTION", "SHARED_EXPERIENCE" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10, "description": "Maximum number of decision makers to look up.", "example": 10 }, "webhook_url": { "type": "string", "format": "uri", "description": "URL that receives the result as a `POST` once the search is done.", "example": "https://hooks.example.com/pipecorn/warm-intros" }, "context": { "type": "object", "additionalProperties": true, "description": "Optional. Any JSON object, sent back untouched in the webhook payload (e.g. your CRM deal id).", "example": { "deal_id": "42" } } } } } } }, "responses": { "201": { "description": "Search started. The result is posted to `webhook_url`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "message": { "type": "string", "example": "Warm path search will begin shortly." }, "request_id": { "type": "string", "format": "uuid", "description": "Sent back as `request_id` in the webhook payload.", "example": "6f1c2a9e-4b7d-4c1e-9a2b-3d4e5f6a7b8c" } } } } }, "example": { "message": { "message": "Warm path search will begin shortly.", "request_id": "6f1c2a9e-4b7d-4c1e-9a2b-3d4e5f6a7b8c" } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "400": { "description": "Bad request — missing `company_linkedin_id` or `webhook_url`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_company": { "value": { "error": "Missing required keys: company_linkedin_id" } }, "missing_webhook": { "value": { "error": "webhook_url key is required in your payload" } } } } } }, "401": { "description": "Unauthorized — missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Persona not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "persona_not_found": { "value": { "error": "Persona not found" } } } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "Invalid parameters, LinkedIn account not connected, or Sales Navigator not connected / expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_company": { "value": { "error": "company_linkedin_id must be a LinkedIn company id" } }, "invalid_webhook": { "value": { "error": "Invalid webhook_url format" } }, "invalid_context": { "value": { "error": "context must be a JSON object" } }, "invalid_limit": { "value": { "error": "limit must be an integer between 1 and 25" } }, "invalid_spotlights": { "value": { "error": "spotlights must be a non-empty array of: SHARED_CONNECTION, SHARED_EXPERIENCE, SHARED_EDUCATION, SHARED_GROUP" } }, "persona_and_titles": { "value": { "error": "persona_id cannot be combined with job_titles or excluded_job_titles" } }, "no_linkedin_credentials": { "value": { "error": "LinkedIn credentials not found. Please connect your LinkedIn account." } }, "no_sales_nav": { "value": { "error": "Sales Navigator credentials expired. Refresh your connection on Pipecorn interface, or set parameter 'live' to false in your request body" } } } } } }, "429": { "description": "Rate limit exceeded (1 request per second per user, or your plan's per-minute limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/lists": { "get": { "operationId": "list_lists", "tags": [ "Lists" ], "summary": "Retrieve all lists", "description": "Returns all lists from the system that the user has access to.", "responses": { "200": { "description": "A JSON array of list objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/Lists" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } } }, "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Cursor" } ] }, "post": { "operationId": "create_list", "tags": [ "Lists" ], "summary": "Create a new list", "description": "Creates a new list in the system.", "requestBody": { "description": "List object that needs to be added", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewList" } } } }, "responses": { "201": { "description": "List created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the created list" }, "linkedin_list_id": { "type": "integer", "format": "int64", "description": "The ID of the created list" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/lists/{id}": { "get": { "operationId": "get_list", "tags": [ "Lists" ], "summary": "Retrieve a specific list", "description": "Returns a specific list by its ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the list to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A list object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/List" } } } } } }, "put": { "operationId": "update_list", "tags": [ "Lists" ], "summary": "Update a list", "description": "Updates a list in the system.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the list to update", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "List object that needs to be updated", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewList" } } } }, "responses": { "200": { "description": "List updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the updated list" }, "linkedin_list_id": { "type": "integer", "format": "int64", "description": "The LinkedIn list ID" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } } } } }, "/personas": { "get": { "operationId": "list_personas", "tags": [ "Personas" ], "summary": "Retrieve all personas", "description": "Returns all personas from the workspace, most recent first.", "responses": { "200": { "description": "The personas", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Personas" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } } } }, "post": { "operationId": "create_persona", "tags": [ "Personas" ], "summary": "Create a new persona", "description": "Creates a persona from job titles, industries, locations and company sizes.", "requestBody": { "description": "The persona to create", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPersona" }, "example": { "name": "VP Grenoble", "job_titles": [ "CEO", "COO" ], "company_size": [ "11-50", "51-200" ] } } } }, "responses": { "201": { "description": "Persona created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Persona" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "`name` or `job_titles` missing, a list field that is not an array, or an invalid persona", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "name is required" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/personas/{uuid}": { "get": { "operationId": "get_persona", "tags": [ "Personas" ], "summary": "Retrieve a specific persona", "description": "Returns a specific persona by its UUID.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the persona to retrieve", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The persona", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Persona" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "No persona with this UUID in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Persona not found" } } } } } }, "put": { "operationId": "update_persona", "tags": [ "Personas" ], "summary": "Update a persona", "description": "Updates a persona. Only the fields you send are changed.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the persona to update", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The fields to change", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonaUpdate" }, "example": { "job_titles": [ "CEO", "CTO" ], "company_size": [ "51-200" ] } } } }, "responses": { "200": { "description": "Persona updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Persona" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "No persona with this UUID in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Persona not found" } } } }, "422": { "description": "A list field that is not an array, an update that leaves no job titles, or an invalid persona", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "At least one job_title is required" } } } } } }, "delete": { "operationId": "delete_persona", "tags": [ "Personas" ], "summary": "Delete a persona", "description": "Deletes a persona by its UUID.", "parameters": [ { "name": "uuid", "in": "path", "required": true, "description": "UUID of the persona to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Persona deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "example": { "message": "Persona deleted successfully" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "404": { "description": "No persona with this UUID in your workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Persona not found" } } } } } } }, "/searches": { "get": { "operationId": "list_searches", "tags": [ "Searches" ], "summary": "Retrieve all searches", "description": "Returns the searches the user has access to. By default only enriched searches are returned. Pass `enriched=false` to return all searches, enriched or not.", "parameters": [ { "name": "enriched", "in": "query", "required": false, "description": "By default (or when set to `true`) only enriched searches are returned. Set to `false` to return all searches, enriched or not.", "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A JSON array of search objects", "content": { "application/json": { "schema": { "type": "object", "properties": { "searches": { "type": "array", "items": { "$ref": "#/components/schemas/Search" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "429": { "description": "Rate limit exceeded (your plan's per-minute limit)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } } } } } }, "/searches/{id}": { "get": { "operationId": "get_search", "tags": [ "Searches" ], "summary": "Retrieve a specific search", "description": "Returns a specific search and its leads by ID.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the search to retrieve", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Filter leads by their qualification status", "schema": { "type": "string", "enum": [ "qualified", "disqualified" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A search object with its leads", "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "$ref": "#/components/schemas/SearchDetail" }, "leads": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } } }, "delete": { "operationId": "delete_search", "tags": [ "Searches" ], "summary": "Delete a search", "description": "Deletes a specific search by its ID. This operation will permanently remove the search and all associated tasks from the system. Only the owner of the search can delete it.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the search to delete", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Search deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Search deleted successfully" } } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "401": { "description": "Unauthorized - The authenticated user does not own the search", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } } }, "404": { "description": "Search not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Search not found" } } } } } }, "422": { "description": "Failed to delete search", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to delete search" } } } } } } } } }, "/locations": { "post": { "operationId": "search_locations", "tags": [ "Miscellaneous" ], "summary": "Get the location id of a specific location", "description": "Resolve location names to IDs used by search endpoints. The `source` parameter selects which catalog to resolve against:\n\n- `live` (default): LinkedIn Sales Navigator. Requires valid LinkedIn credentials on the account.\n- `database`: the internal geo database used by the company/lead database search endpoints. No LinkedIn credentials required.\n- `hiring`: the hiring-signal location catalog. No LinkedIn credentials required.\n\nThe shape of each returned item depends on the `source` (see the response examples below).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "San Francisco", "description": "The name of the location to get the id of" }, "source": { "type": "string", "enum": [ "live", "database", "hiring" ], "default": "live", "example": "live", "description": "Which location catalog to resolve against. `live` uses LinkedIn Sales Navigator (requires LinkedIn credentials); `database` uses the internal geo database; `hiring` uses the hiring-signal catalog. Defaults to `live` when omitted." } }, "example": { "name": "San Francisco", "source": "live" } } } } }, "responses": { "200": { "description": "Locations retrieved successfully. Each item always includes `id` and `name`; additional fields depend on the `source`.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the location, to be passed to search endpoints." }, "name": { "type": "string", "description": "The name of the location. For `source: live` this is the full display name." }, "display_name": { "type": "string", "description": "Full human-readable location name. Returned for `source: hiring` only." }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code. Returned for `source: hiring` only." }, "type": { "type": "string", "description": "Geo-zone kind (e.g. country, region, city). Returned for `source: database` only." }, "subtitle": { "type": "string", "description": "Human-readable context such as parent regions and kind. Returned for `source: database` only." } } } }, "examples": { "live": { "summary": "source: live (LinkedIn Sales Navigator)", "value": [ { "name": "San Francisco Bay Area", "id": "90000084" }, { "name": "San Francisco, California, United States", "id": "102277331" } ] }, "database": { "summary": "source: database (internal geo database)", "value": [ { "id": "country:fr", "name": "France", "type": "country", "subtitle": "country" } ] }, "hiring": { "summary": "source: hiring (hiring-signal catalog)", "value": [ { "id": "1", "display_name": "Paris, France", "name": "Paris", "country_code": "FR" } ] } } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/credits": { "get": { "operationId": "get_credits", "tags": [ "Miscellaneous" ], "summary": "Retrieve credit balances", "description": "Returns the current credit balances and limits for various services", "responses": { "200": { "description": "A JSON array of list objects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Credit" } } } } } } } }, "/credits_consumption": { "get": { "operationId": "get_credits_consumption", "tags": [ "Miscellaneous" ], "summary": "Retrieve credit consumption for a date range", "description": "Returns your current credit balance and the total enrichment credits consumed between a start and end date (inclusive). Dates are provided as `YYYY-MM-DD` query parameters and are interpreted in UTC, from the start of `start_date` to the end of `end_date`.", "parameters": [ { "name": "start_date", "in": "query", "required": true, "description": "Start of the range (inclusive), formatted as YYYY-MM-DD.", "schema": { "type": "string", "format": "date", "example": "2026-01-01" } }, { "name": "end_date", "in": "query", "required": true, "description": "End of the range (inclusive), formatted as YYYY-MM-DD. Must be on or after start_date.", "schema": { "type": "string", "format": "date", "example": "2026-01-31" } } ], "responses": { "200": { "description": "Current balance and credits consumed over the requested range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditConsumption" } } }, "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "422": { "description": "Missing or invalid date parameters (missing date, malformed date, or start_date after end_date)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account": { "get": { "operationId": "get_account", "tags": [ "Miscellaneous" ], "summary": "Retrieve account information", "description": "Returns the current account information: subscription plan, the email address of the user the API key belongs to, and the integration session status", "responses": { "200": { "description": "Account information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } } } } }, "/whatsapp_validations": { "post": { "operationId": "check_whatsapp_reachability", "tags": [ "WhatsApp" ], "summary": "Check WhatsApp reachability", "description": "Checks whether a single phone number is reachable on WhatsApp. Charges 1 credit per request.", "requestBody": { "description": "The phone number to check, in E.164 format.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappValidationRequest" }, "example": { "validate_phone": "+33612345678" } } } }, "responses": { "200": { "description": "Check completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappValidationResponse" }, "examples": { "on_whatsapp": { "summary": "Number is reachable on WhatsApp", "value": { "whatsapp": { "status": "on_whatsapp" } } }, "not_on_whatsapp": { "summary": "Number is not on WhatsApp", "value": { "whatsapp": { "status": "not_on_whatsapp" } } } } } }, "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } } }, "401": { "description": "Missing or invalid API key, or the workspace is not allowed to use the API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized" } } } }, "402": { "description": "The workspace does not have the 1 credit the check costs. Returned before the provider is called, and also when a concurrent request drains the balance before this one is charged. Nothing is spent.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientCreditsError" }, "example": { "error": "Not enough enrichment credits left", "code": "insufficient_credits", "top_up_url": "https://app.pipecorn.com/settings/subscriptions/credits" } } } }, "403": { "description": "The workspace weekly enrichment credit limit is reached. Buying credits does not lift it, so no `top_up_url` is returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceLimitError" }, "example": { "error": "You have reached your weekly enrichment credit limit for this workspace", "code": "workspace_limit_exceeded" } } } }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "422": { "description": "The phone is missing or invalid, or the provider check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_phone": { "summary": "Phone not provided", "value": { "error": "validate_phone is required" } }, "invalid_phone": { "summary": "Phone is not a valid number", "value": { "error": "validate_phone is not a valid phone number" } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Your Pipecorn API key, created at https://app.pipecorn.com/settings/apis/keys. Rate limits are counted per user, not per key." } }, "schemas": { "Error": { "required": [ "error" ], "type": "object", "properties": { "error": { "description": "Human-readable error message. A few validation errors return a list of messages, or an object with more detail, instead of a single string.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "object" } ] } } }, "LeadEnrichment": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First name of the lead" }, "last_name": { "type": "string", "description": "Last name of the lead" }, "title": { "type": "string", "description": "Current job title" }, "linkedin_profile_url": { "type": "string", "format": "uri", "description": "URL to the lead's LinkedIn profile" }, "linkedin_id_url": { "type": "string", "format": "uri", "description": "Internal-URN LinkedIn profile URL, derived from `regular_urn` (`https://www.linkedin.com/in/`). Stable across vanity-URL changes.", "nullable": true }, "regular_urn": { "type": "string", "description": "LinkedIn regular URN identifier", "nullable": true }, "lk_headline": { "type": "string", "description": "LinkedIn headline" }, "lk_connections_count": { "type": "integer", "description": "Number of LinkedIn connections" }, "years_in_position": { "type": "integer", "nullable": true, "description": "Number of years in current position" }, "months_in_position": { "type": "integer", "nullable": true, "description": "Number of months in current position" }, "years_in_company": { "type": "integer", "nullable": true, "description": "Number of years in current company" }, "months_in_company": { "type": "integer", "nullable": true, "description": "Number of months in current company" }, "current_position": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/LeadPosition" } ], "description": "The current role. Also the first entry of `positions`, where it carries `current: true`." }, "positions": { "type": "array", "description": "The person's role history.", "items": { "$ref": "#/components/schemas/LeadPosition" } }, "title_description": { "type": "string", "description": "Description of the current title/role" }, "summary": { "type": "string", "nullable": true, "description": "Profile summary" }, "full_name": { "type": "string", "description": "Full name of the lead" }, "sales_navigator_profile_url": { "type": "string", "nullable": true, "format": "uri", "description": "Sales Navigator profile URL, derived from the person's Sales Navigator (`ACw…`) key when the people database holds one" }, "linkedin_url": { "type": "string", "format": "uri", "description": "Public LinkedIn profile URL, falling back to the internal-URN URL", "example": "https://www.linkedin.com/in/mathieu-brun-picard" }, "location": { "type": "string", "description": "Where the person is based", "example": "San Francisco Bay Area" }, "num_of_followers": { "type": "integer", "nullable": true, "description": "LinkedIn follower count", "example": 7880 }, "initials": { "type": "string", "nullable": true, "description": "Initials of the person", "example": "MB" }, "previous_position": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/LeadPosition" } ], "description": "The role held before the current one." }, "urn": { "type": "string", "nullable": true, "description": "LinkedIn Sales Navigator URN identifier" }, "start_date_job": { "type": "string", "format": "date", "nullable": true, "description": "Start date in the current position. Pipecorn's people database holds a single current-role start date and no separate company start, so this matches `start_date_company`." }, "start_date_company": { "type": "string", "format": "date", "nullable": true, "description": "Start date at the current company. See `start_date_job`." } }, "description": "Enriched person. Any field Pipecorn's people database does not hold for this person is returned as `null`." }, "NewLeadSearch": { "required": [ "search_url", "name" ], "type": "object", "properties": { "search_url": { "type": "string", "format": "uri", "description": "The LinkedIn search URL to extract leads from" }, "webhook_url": { "type": "string", "format": "uri", "description": "Optional webhook URL to receive notifications when the search is complete" }, "name": { "type": "string", "description": "Name of the lead search" }, "streaming": { "type": "boolean", "description": "When set to true, leads will be sent individually to the webhook_url as they are found. This is ideal for integration with platforms like Clay that process leads in real-time.", "default": false, "example": true }, "custom": { "type": "object", "description": "Custom fields to include with the lead search that will be returned in the webhook (like crm id, etc.)", "additionalProperties": true, "example": { "hubspot_id": "134567" } }, "limit": { "type": "integer", "description": "Optional parameter to limit the number of results returned. If not specified, all matching leads will be returned.", "minimum": 1, "example": 100 }, "scale": { "type": "boolean", "description": "When set to true, increases request volume by omitting the following fields: connections_count, headline, and vanity LinkedIn profile URL. You will still receive a LinkedIn profile URL, but it will use the user ID instead of the vanity URL (e.g., https://www.linkedin.com/in/mathieu-brun-picard/).", "default": false, "example": true } } }, "InsufficientCreditsError": { "required": [ "error", "code", "top_up_url" ], "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message. Endpoints priced per result report the shortfall instead, e.g. \"Not enough enrichment credits. You need 30 credits but only have 5 available.\"", "example": "Not enough enrichment credits left" }, "code": { "type": "string", "enum": [ "insufficient_credits" ], "description": "Machine-readable error code" }, "top_up_url": { "type": "string", "format": "uri", "description": "Absolute URL of the credits page. Buy credits there, then replay the request.", "example": "https://app.pipecorn.com/settings/subscriptions/credits" } } }, "WorkspaceLimitError": { "required": [ "error", "code" ], "type": "object", "properties": { "error": { "type": "string", "example": "You have reached your weekly enrichment credit limit for this workspace" }, "code": { "type": "string", "enum": [ "workspace_limit_exceeded" ], "description": "Machine-readable error code. A 403 carrying any other code is a permission problem, not a spending limit." } } }, "LeadPosition": { "type": "object", "description": "A role held by the person, in the order the people database holds them: the current role first, then past roles. Keys absent from the record are omitted.", "properties": { "pos_id": { "type": "integer", "description": "LinkedIn position identifier", "example": 2316534272 }, "title": { "type": "string", "description": "Job title", "example": "Co-founder & CEO" }, "current": { "type": "boolean", "description": "Whether the person still holds this role", "example": true }, "company_name": { "type": "string", "description": "Name of the company", "example": "Pipecorn" }, "name": { "type": "string", "description": "Alias of `company_name`", "example": "Pipecorn" }, "company_id": { "type": "string", "description": "Pipecorn company id", "example": "3735071" }, "company_urn": { "type": "string", "description": "LinkedIn company URN", "example": "urn:li:fs_salesCompany:3735071" }, "company_domain": { "type": "string", "description": "Company website domain", "example": "pipecorn.com" }, "company_logo": { "type": "string", "format": "uri", "description": "Company logo URL" }, "description": { "type": "string", "description": "Role or company description" }, "location": { "type": "string", "description": "Where the role is based", "example": "San Francisco Bay Area" }, "employment_type": { "type": "string", "description": "Employment type, when the record carries one" }, "started_on": { "type": "object", "nullable": true, "description": "Year and month the role started or ended", "properties": { "year": { "type": "integer", "example": 2024 }, "month": { "type": "integer", "example": 1 } } }, "ended_on": { "type": "object", "nullable": true, "description": "Year and month the role started or ended", "properties": { "year": { "type": "integer", "example": 2024 }, "month": { "type": "integer", "example": 1 } } }, "tenure_at_position": { "type": "object", "nullable": true, "description": "Time spent in this role", "properties": { "num_years": { "type": "integer", "example": 2 }, "num_months": { "type": "integer", "example": 0 } } }, "tenure_at_company": { "type": "object", "nullable": true, "description": "Time spent at this company", "properties": { "num_years": { "type": "integer", "example": 2 }, "num_months": { "type": "integer", "example": 0 } } } } }, "AccountEnrichment": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Company name", "example": "Pipecorn" }, "description": { "type": "string", "description": "Company description", "example": "Ready to hunt without running ?\n\n👨‍👩‍👦‍👦 Squad of 10 outbound experts +\n🦁 One tool to automate your campaigns" }, "industry": { "type": "string", "description": "Primary industry", "example": "Technology, Information and Internet" }, "company_type": { "type": "string", "description": "Company type", "example": "Privately Held" }, "location": { "type": "string", "description": "Full location string", "example": "Paris, Île-de-France, France" }, "headquarters": { "type": "object", "properties": { "country": { "type": "string", "description": "Country name", "example": "France" }, "city": { "type": "string", "description": "City name", "example": "Paris" } } }, "revenue_range": { "type": "object", "properties": { "estimated_min_revenue": { "type": "object", "properties": { "currency_code": { "type": "string", "example": "USD" }, "amount": { "type": "number", "example": 500 }, "unit": { "type": "string", "example": "THOUSAND" } } }, "estimated_max_revenue": { "type": "object", "properties": { "currency_code": { "type": "string", "example": "USD" }, "amount": { "type": "number", "example": 1 }, "unit": { "type": "string", "example": "MILLION" } } } }, "description": "Estimated revenue bounds in USD, each expressed as an amount plus the largest unit it clears (`THOUSAND`, `MILLION`, `BILLION`, `TRILLION`, or `NONE` below a thousand)." }, "website": { "type": "string", "description": "Company website as stored, including scheme", "example": "http://pipecorn.com" }, "domain": { "type": "string", "description": "Company website domain", "example": "pipecorn.com" }, "linkedin_id": { "type": "string", "description": "LinkedIn company id", "example": "104885158" }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn company profile URL", "example": "https://www.linkedin.com/company/pipecorn" }, "entity_urn": { "type": "string", "description": "LinkedIn company URN identifier", "example": "urn:li:fs_salesCompany:104885158" }, "employee_count": { "type": "integer", "description": "Current number of employees", "example": 13 }, "employee_display_count": { "type": "string", "description": "Employee count as a display string", "example": "5" }, "employee_range": { "type": "string", "description": "Employee count range", "example": "2-10" }, "employee_count_info": { "type": "object", "description": "Detailed employee count information", "properties": { "monthly_change": { "type": "integer", "description": "Monthly employee count change", "example": -17 }, "employee_count": { "type": "integer", "description": "Current number of employees", "example": 5 }, "employee_display_count": { "type": "string", "description": "Employee count as a display string", "example": "5" } } }, "department_headcount": { "type": "object", "description": "Current headcount per department. Keys are department names.", "additionalProperties": { "type": "integer" }, "example": { "Engineering": 1, "Business Development": 4, "Marketing": 2 } }, "headcount_growth": { "type": "object", "description": "Company-wide headcount growth over each window, in percent.", "properties": { "mom": { "type": "number", "description": "Month-on-month change, in percent" }, "qoq": { "type": "number", "description": "Quarter-on-quarter change, in percent" }, "six_months": { "type": "number", "description": "Six-month change, in percent" }, "yoy": { "type": "number", "description": "Year-on-year change, in percent" }, "two_years": { "type": "number", "description": "Two-year change, in percent" } }, "example": { "mom": 0, "qoq": 20, "sixMonths": 33.33, "yoy": 33.33, "twoYears": 140 } }, "department_headcount_growth": { "type": "object", "description": "Headcount growth per department. Keys are department names; each value carries the same growth windows as `headcount_growth`.", "additionalProperties": { "type": "object", "description": "Headcount growth for this department, in percent.", "properties": { "mom": { "type": "number", "description": "Month-on-month change, in percent" }, "qoq": { "type": "number", "description": "Quarter-on-quarter change, in percent" }, "six_months": { "type": "number", "description": "Six-month change, in percent" }, "yoy": { "type": "number", "description": "Year-on-year change, in percent" }, "two_years": { "type": "number", "description": "Two-year change, in percent" } }, "example": { "mom": 100, "qoq": 100 } }, "example": { "Marketing": { "mom": 100, "qoq": 100, "sixMonths": 100, "yoy": 100 } } }, "monthly_visitors": { "type": "integer", "description": "Estimated monthly visitors to the company website", "example": 33 }, "monthly_visitor_mom_pct": { "type": "number", "description": "Month-on-month change in monthly visitors, in percent", "example": 0 }, "monthly_visitor_qoq_pct": { "type": "number", "description": "Quarter-on-quarter change in monthly visitors, in percent", "example": 0 }, "funding_and_investment": { "type": "object", "description": "Funding history, when Pipecorn holds any for the company.", "properties": { "crunchbase_total_investment_usd": { "type": "number", "nullable": true, "description": "Total investment raised, in USD" }, "last_funding_round_type": { "type": "string", "nullable": true, "description": "Type of the most recent round, e.g. `series_a`" }, "last_funding_round_investment_usd": { "type": "number", "nullable": true, "description": "Amount raised in the most recent round, in USD" }, "days_since_last_fundraise": { "type": "integer", "nullable": true, "description": "Days since the most recent round closed" }, "crunchbase_investors": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Named investors" }, "funding_milestones_timeseries": { "type": "array", "nullable": true, "items": { "type": "object" }, "description": "Funding milestones over time" }, "acquired_by": { "type": "string", "nullable": true, "description": "Acquirer, if the company was acquired" }, "acquisitions": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Companies this company has acquired" } } }, "last_updated": { "type": "string", "format": "date-time", "description": "When Pipecorn last refreshed this company record", "example": "2026-07-29T12:46:59" } }, "description": "Enriched company account. Any field Pipecorn's companies database does not hold for this company is omitted from the response rather than returned as `null`." }, "EnrichmentRequest": { "type": "object", "properties": { "webhook_url": { "type": "string", "format": "uri", "description": "Webhook URL to receive enrichment results" }, "phone_country_codes": { "type": "array", "items": { "type": "string", "description": "ISO 3166-1 alpha-2 country code (e.g. \"US\", \"FR\", \"GB\")" }, "description": "Optional. Restrict phone enrichment to phone numbers from these countries. When omitted, the user's account-level default phone country codes are applied." }, "phone_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "all", "mobile" ] }, "default": [ "all" ], "description": "Optional. Filters the phone numbers returned by phone enrichment. `[\"all\"]` (default) returns every number found; `[\"mobile\"]` returns only mobile numbers (`type` of `mobile` or `fixed_or_mobile`) and drops landlines, VoIP, toll-free and other non-mobile numbers. With `[\"mobile\"]` the waterfall keeps querying providers until one returns a mobile number. Any other value is rejected with `422`. Ignored unless `enrichment_type` includes `phone`." }, "custom": { "type": "object", "description": "Custom fields to include with the enrichment that will be returned in the webhook (like crm id, etc.)", "additionalProperties": true } }, "oneOf": [ { "title": "Email enrichment", "required": [ "enrichment_type", "firstname", "lastname" ], "properties": { "enrichment_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "email" ] }, "description": "Set to [\"email\"] to find and validate the professional email." }, "firstname": { "type": "string", "description": "First name of the contact." }, "lastname": { "type": "string", "description": "Last name of the contact." }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" }, "domain": { "type": "string", "description": "Company domain.", "example": "pipecorn.com" }, "company_name": { "type": "string", "description": "Company name.", "example": "Pipecorn" } }, "anyOf": [ { "required": [ "linkedin_url" ] }, { "required": [ "domain" ] }, { "required": [ "company_name" ] } ], "description": "Requires `firstname`, `lastname`, and at least one identifier: `linkedin_url`, `domain`, or `company_name`." }, { "title": "Phone enrichment", "required": [ "enrichment_type", "linkedin_url" ], "properties": { "enrichment_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "phone" ] }, "description": "Set to [\"phone\"] to find phone numbers." }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" } }, "description": "Requires only the contact's `linkedin_url` (`firstname`/`lastname` are not needed)." }, { "title": "Personal email enrichment", "required": [ "enrichment_type", "linkedin_url" ], "properties": { "enrichment_type": { "type": "array", "maxItems": 1, "items": { "type": "string", "enum": [ "personal_email" ] }, "description": "Set to [\"personal_email\"]. Requires per-user GDPR consent." }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL of the contact.", "example": "https://www.linkedin.com/in/mathieu-brun-picard/" } }, "description": "Requires the contact's `linkedin_url` and account-level GDPR consent (`firstname`/`lastname` are not needed)." } ] }, "Lists": { "type": "object", "properties": { "lists": { "type": "array", "items": { "$ref": "#/components/schemas/List" } } } }, "List": { "type": "object", "properties": { "name": { "description": "The name of the list", "type": "string", "example": "Tech Companies 2024" }, "id": { "description": "The id of the list", "type": "string", "format": "uuid", "example": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc" }, "linkedin_list_id": { "description": "The LinkedIn ID of the list", "type": "integer", "format": "int64", "example": 123456789 }, "created_at": { "description": "The creation date of the list", "type": "string", "format": "date-time", "example": "2024-01-01T00:00:00Z" }, "updated_at": { "description": "The last modified date of the list", "type": "string", "format": "date-time", "example": "2024-01-02T00:00:00Z" }, "status": { "description": "The current status of the list import process", "type": "string", "enum": [ "pending", "completed", "failed" ], "default": "pending", "example": "completed" } } }, "NewList": { "required": [ "name", "companies" ], "type": "object", "properties": { "name": { "description": "The name of the list", "type": "string" }, "webhook_url": { "description": "URL to be notified when the list import is complete", "type": "string", "format": "uri" }, "companies": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "description": "The name of the company", "type": "string", "example": "Pipecorn" }, "country_code": { "description": "The country code where the company is located. Optional but increases the chance of a match.", "type": "string", "example": "FR" }, "domain": { "description": "The company's domain address. Website URL can work as well. Optional but increases the chance of a match.", "type": "string", "example": "pipecorn.com" }, "linkedin_url": { "description": "The company's LinkedIn profile URL (regular or Sales Navigator). Adding it provides a 100% match.", "type": "string", "format": "uri", "example": "https://www.linkedin.com/company/pipecorn" } } }, "example": [ { "name": "Pipecorn", "country_code": "FR", "domain": "pipecorn.com", "linkedin_url": "https://www.linkedin.com/company/pipecorn" }, { "name": "Google", "country_code": "US", "domain": "google.com", "linkedin_url": "https://www.linkedin.com/company/google" } ] } } }, "Pagination": { "type": "object", "required": [ "per_page", "total_count", "has_more" ], "properties": { "page": { "type": "integer", "description": "Current page number. Absent when the request used `cursor`." }, "per_page": { "type": "integer", "description": "Rows per page." }, "total_count": { "type": "integer", "description": "Rows across all pages." }, "has_more": { "type": "boolean", "description": "Whether another page follows." }, "next_cursor": { "type": "string", "description": "Pass it as `cursor` to get the next page. Absent on the last page." } } }, "Persona": { "type": "object", "properties": { "uuid": { "description": "The unique identifier of the persona", "type": "string", "format": "uuid", "example": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc" }, "name": { "description": "The name of the persona", "type": "string", "example": "VP Grenoble" }, "description": { "description": "Free-text description of the persona", "type": "string", "nullable": true }, "included_job_titles": { "description": "Job titles included", "type": "array", "items": { "type": "string" }, "example": [ "CEO", "COO", "Cofounder" ] }, "excluded_job_titles": { "description": "Job titles excluded", "type": "array", "items": { "type": "string" } }, "included_industries": { "description": "Industry IDs included", "type": "array", "items": { "type": "string" } }, "excluded_industries": { "description": "Industry IDs excluded", "type": "array", "items": { "type": "string" } }, "included_locations": { "description": "Location IDs included", "type": "array", "items": { "type": "string" } }, "excluded_locations": { "description": "Location IDs excluded", "type": "array", "items": { "type": "string" } }, "company_size": { "description": "Company headcount ranges", "type": "array", "items": { "type": "string" }, "example": [ "11-50", "51-200" ] }, "sales_nav_url": { "description": "Sales Navigator search URL built from the persona filters", "type": "string", "nullable": true }, "created_at": { "description": "The creation date of the persona", "type": "string", "format": "date-time", "example": "2024-09-09T15:15:15.951Z" }, "updated_at": { "description": "The last modified date of the persona", "type": "string", "format": "date-time", "example": "2024-09-09T15:15:15.951Z" } } }, "Personas": { "type": "object", "properties": { "personas": { "type": "array", "items": { "$ref": "#/components/schemas/Persona" } } }, "example": { "personas": [ { "uuid": "8e1dcba0-f0bb-4071-99fc-f18ba6559ccc", "name": "VP Grenoble", "description": null, "included_job_titles": [ "VP of Engineering", "CTO" ], "excluded_job_titles": [], "included_industries": [], "excluded_industries": [], "included_locations": [], "excluded_locations": [], "company_size": [ "51-200" ], "sales_nav_url": "https://www.linkedin.com/sales/search/people?query=...", "created_at": "2024-09-09T15:15:15.951Z", "updated_at": "2024-09-09T15:15:15.951Z" } ] } }, "NewPersona": { "type": "object", "required": [ "name", "job_titles" ], "properties": { "name": { "description": "Name of the persona", "type": "string", "example": "VP Grenoble" }, "description": { "description": "Free-text description of the persona", "type": "string", "example": "Engineering leaders in Grenoble" }, "job_titles": { "description": "Job titles to include", "type": "array", "items": { "type": "string" }, "example": [ "CEO", "COO", "Cofounder" ] }, "excluded_job_titles": { "description": "Job titles to exclude", "type": "array", "items": { "type": "string" }, "example": [ "Intern" ] }, "ai_expand_job_titles": { "description": "Expand `job_titles` with AI-suggested variants before saving. Suggested titles to exclude are added to `excluded_job_titles`.", "type": "boolean", "default": false }, "included_industries": { "description": "Industry IDs to include", "type": "array", "items": { "type": "string" } }, "excluded_industries": { "description": "Industry IDs to exclude", "type": "array", "items": { "type": "string" } }, "included_locations": { "description": "Location IDs to include. Look them up with the locations endpoint.", "type": "array", "items": { "type": "string" } }, "excluded_locations": { "description": "Location IDs to exclude", "type": "array", "items": { "type": "string" } }, "company_size": { "description": "Company headcount ranges. The LinkedIn size codes `A`–`I` are also accepted for older integrations, and are returned as sent.", "type": "array", "items": { "type": "string", "enum": [ "Self-employed", "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "11-50", "51-200" ] } } }, "PersonaUpdate": { "type": "object", "description": "Only the fields you send are changed. Included and excluded lists of the same kind (job titles, industries, locations) are replaced together: sending either one replaces both.", "properties": { "name": { "description": "Name of the persona. Omit or leave blank to keep the current name.", "type": "string", "example": "VP Grenoble" }, "description": { "description": "Free-text description of the persona. Send null to clear it; omit to keep it.", "type": "string", "example": "Engineering leaders in Grenoble" }, "job_titles": { "description": "Job titles to include. Replaces the stored list when sent; omit to keep it.", "type": "array", "items": { "type": "string" }, "example": [ "CEO", "COO", "Cofounder" ] }, "excluded_job_titles": { "description": "Job titles to exclude. Replaces the stored list when sent; omit to keep it.", "type": "array", "items": { "type": "string" }, "example": [ "Intern" ] }, "ai_expand_job_titles": { "description": "Expand `job_titles` with AI-suggested variants before saving. Suggested titles to exclude are added to `excluded_job_titles`.", "type": "boolean", "default": false }, "included_industries": { "description": "Industry IDs to include. Replaces the stored list when sent; omit to keep it.", "type": "array", "items": { "type": "string" } }, "excluded_industries": { "description": "Industry IDs to exclude. Replaces the stored list when sent; omit to keep it.", "type": "array", "items": { "type": "string" } }, "included_locations": { "description": "Location IDs to include. Look them up with the locations endpoint.. Replaces the stored list when sent; omit to keep it.", "type": "array", "items": { "type": "string" } }, "excluded_locations": { "description": "Location IDs to exclude. Replaces the stored list when sent; omit to keep it.", "type": "array", "items": { "type": "string" } }, "company_size": { "description": "Company headcount ranges. Replaces the stored list when sent; omit to keep it. The LinkedIn size codes `A`–`I` are also accepted for older integrations, and are returned as sent.", "type": "array", "items": { "type": "string", "enum": [ "Self-employed", "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "example": [ "11-50", "51-200" ] } } }, "Search": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the search" }, "name": { "type": "string", "description": "The name of the search" }, "leads_count": { "type": "integer", "description": "Number of leads in the search" }, "created_at": { "type": "string", "format": "date-time", "description": "When the search was created" } } }, "SearchDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "The unique identifier for the search" }, "name": { "type": "string", "description": "The name of the search" }, "status": { "type": "string", "enum": [ "finished", "not_started", "ongoing", "rate_limited", "unauthorized", "forbidden", "error" ], "description": "The current status of the search" }, "results_ready": { "type": "boolean", "description": "Whether the search has finished and its leads are available. When false, the leads array is omitted." } } }, "Lead": { "type": "object", "properties": { "lead": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "QUALIFIED", "DISQUALIFIED" ], "description": "Current qualification status of the lead" }, "rejection_reasons": { "type": "array", "items": { "type": "string" }, "description": "Reasons for rejection if disqualified" }, "first_name": { "type": "string", "description": "First name of the lead" }, "last_name": { "type": "string", "description": "Last name of the lead" }, "gender": { "type": "string", "nullable": true, "description": "Gender of the lead" }, "email": { "type": "string", "nullable": true, "description": "Most probable email address" }, "email_status": { "type": "string", "nullable": true, "description": "Deliverability status of the email (e.g. Valid, Catch-all)" }, "phone": { "type": "array", "items": { "type": "object" }, "description": "List of phone number records" }, "linkedin_url": { "type": "string", "format": "uri", "nullable": true, "description": "LinkedIn profile URL" }, "linkedin_id_url": { "type": "string", "format": "uri", "nullable": true, "description": "LinkedIn profile URL built from the member's stable id" }, "profile_image_url": { "type": "string", "format": "uri", "nullable": true, "description": "Profile image URL" }, "location": { "type": "string", "nullable": true, "description": "Location of the lead" }, "title": { "type": "string", "nullable": true, "description": "Job title of the lead" }, "lk_headline": { "type": "string", "nullable": true, "description": "LinkedIn headline" }, "hire_type": { "type": "string", "enum": [ "new_hire", "promoted" ], "nullable": true, "description": "Whether the lead recently joined the company (new_hire) or was promoted within it" }, "current_position": { "type": "object", "nullable": true, "description": "The lead's current position" }, "previous_position": { "type": "object", "nullable": true, "description": "The lead's previous position" }, "positions": { "type": "array", "items": { "type": "object" }, "nullable": true, "description": "The lead's position history" }, "years_in_position": { "type": "integer", "description": "Years in current position (0 when unknown)" }, "months_in_position": { "type": "integer", "description": "Months in current position (0 when unknown)" }, "years_in_company": { "type": "integer", "description": "Years in current company (0 when unknown)" }, "months_in_company": { "type": "integer", "description": "Months in current company (0 when unknown)" } } }, "company": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Company name" }, "cleaned_name": { "type": "string", "nullable": true, "description": "Cleaned company name" }, "website": { "type": "string", "format": "uri", "nullable": true, "description": "Company website" }, "location": { "type": "string", "nullable": true, "description": "Company location" }, "industry": { "type": "string", "nullable": true, "description": "Company industry" }, "headquarters": { "type": "object", "nullable": true, "description": "Company headquarters details (returned only when available as structured data)" }, "description": { "type": "string", "nullable": true, "description": "Company description" }, "linkedin_url": { "type": "string", "format": "uri", "nullable": true, "description": "Company LinkedIn profile URL" }, "linkedin_id": { "type": "string", "nullable": true, "description": "Company LinkedIn identifier" }, "employee_range": { "type": "string", "nullable": true, "description": "Company employee count range" }, "company_profile_picture": { "type": "string", "format": "uri", "nullable": true, "description": "Company profile picture URL" } } } } }, "Credit": { "type": "object", "properties": { "credits": { "type": "object", "properties": { "enrichment": { "type": "integer", "description": "Number of enrichment credits remaining", "example": 3000 }, "daily_profile_scraping": { "type": "integer", "description": "Number of daily profile scraping credits remaining", "example": 1500 }, "daily_company_import": { "type": "integer", "description": "Number of daily company import credits remaining", "example": 1000 }, "monthly_company_import": { "type": "integer", "description": "Number of monthly company import credits remaining", "example": 10000 } } }, "limits": { "type": "object", "properties": { "daily_profile_scraping": { "type": "integer", "example": 2500, "description": "Maximum daily profile scraping credits" }, "daily_company_import": { "type": "integer", "example": 1000, "description": "Maximum daily company import credits" }, "monthly_company_import": { "type": "integer", "example": 10000, "description": "Maximum monthly company import credits" } } } } }, "CreditConsumption": { "type": "object", "properties": { "current_credit_balance": { "type": "integer", "description": "Your current enrichment credit balance.", "example": 3000 }, "consumption": { "type": "object", "properties": { "start_date": { "type": "string", "format": "date", "description": "Start of the range (inclusive), echoed back.", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "description": "End of the range (inclusive), echoed back.", "example": "2026-01-31" }, "credits_consumed": { "type": "integer", "description": "Total enrichment credits consumed within the range.", "example": 1250 } } } } }, "Account": { "type": "object", "properties": { "account": { "type": "object", "properties": { "plan": { "type": "string", "description": "The current subscription plan", "example": "scale" }, "email": { "type": "string", "format": "email", "description": "Email address of the user the API key belongs to", "example": "jane@acme.com" } } }, "integrations": { "type": "object", "properties": { "linkedin_session_valid": { "type": "boolean", "description": "Whether the LinkedIn session is still valid", "example": true }, "sales_navigator_session_valid": { "type": "boolean", "description": "Whether the Sales Navigator session is still valid", "example": true } } } } }, "WhatsappValidationRequest": { "type": "object", "required": [ "validate_phone" ], "properties": { "validate_phone": { "type": "string", "description": "The phone number to check, in E.164 format (e.g. +33612345678).", "example": "+33612345678" } } }, "WhatsappValidationResponse": { "type": "object", "properties": { "whatsapp": { "type": "object", "properties": { "status": { "type": "string", "description": "The WhatsApp reachability status of the phone number.", "enum": [ "on_whatsapp", "not_on_whatsapp", "check_failed" ] } } } } } }, "headers": { "RateLimit-Limit": { "description": "Requests allowed per minute on your plan for this group of endpoints. Absent for unlimited accounts and on endpoints exempt from the plan limit.", "schema": { "type": "integer", "example": 100 } }, "RateLimit-Remaining": { "description": "Requests left in the current one-minute window.", "schema": { "type": "integer", "example": 97 } }, "RateLimit-Reset": { "description": "Seconds until the current window resets and `RateLimit-Remaining` is back to `RateLimit-Limit`.", "schema": { "type": "integer", "example": 42 } }, "Retry-After": { "description": "Seconds to wait before retrying. Sent when the plan limit or a request still in progress caused the error.", "schema": { "type": "integer", "example": 42 } }, "Idempotent-Replayed": { "description": "`true` when this response is a replay of an earlier request sent with the same `Idempotency-Key`. Nothing was run or charged again.", "schema": { "type": "string", "enum": [ "true" ] } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique value you generate per operation, such as a UUID. Retrying with the same key and the same body returns the stored response instead of running the request again, so a retry after a timeout never charges twice. Successful responses are kept for 24 hours; a failed request is not stored and can be retried with the same key.", "schema": { "type": "string", "maxLength": 255, "example": "4f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11" } }, "Page": { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1. Prefer `cursor`: pages shift when rows are added between two calls.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "description": "Rows per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "The `pagination.next_cursor` of the previous page, passed back unchanged. Returns the rows that follow it, even if rows were added in between. Omit it for the first page.", "schema": { "type": "string", "example": "WyIyMDI2LTEwLTE3VDEwOjAwOjAwLjAwMDAwMFoiLDQyXQ" } } }, "responses": { "IdempotencyConflict": { "description": "A request with this `Idempotency-Key` is still being processed. Wait for the `Retry-After` delay and retry with the same key.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "idempotency_key_in_use" ] } } }, "example": { "error": "A request with this Idempotency-Key is still being processed", "code": "idempotency_key_in_use" } } } } } } }