{"openapi":"3.1.0","info":{"title":"NetworkHQ Public API","version":"1.0.0","description":"External REST API for reading campaigns and campaign leads, managing lead lists and leads, enriching lead profiles, reading LinkedIn sender accounts, and reading and sending conversation messages.\n\n**Authentication** — every request must send a workspace API key as a bearer token: `Authorization: Bearer <api_key>`. API keys are scoped; an endpoint returns 403 when the key is missing the scope it requires (each operation lists its scope below) and 401 when the key is absent, malformed, or revoked.\n\n**Rate limiting** — requests are capped at 60 per minute per API key using a fixed window. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (a Unix timestamp in seconds) headers, and exceeding the limit returns 429.\n\n**Pagination** — list endpoints use cursor pagination. Pass `limit` (1–500, default 100) and the `next_cursor` from the previous response's `pagination` object to fetch the next page; `has_more` is `false` on the last page."},"servers":[{"url":"https://api.networkhq.io/api/v1"}],"tags":[{"name":"Campaigns","description":"Read outreach campaign status and performance summary metrics."},{"name":"LinkedIn accounts","description":"Read workspace sender accounts and campaign sender assignments."},{"name":"Lead lists","description":"Create one or more lead lists, list lead lists, and inspect lead lists in the API key workspace."},{"name":"Leads","description":"Import one or more leads, list, retrieve, and enrich leads."},{"name":"Conversations","description":"Read LinkedIn conversations, message history, and send messages into existing threads."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["limit","has_more","next_cursor"]},"CampaignLinkedInAccount":{"type":"object","properties":{"id":{"type":"string"},"profileName":{"type":["string","null"]}},"required":["id","profileName"]},"CampaignLeadList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"CampaignLeadBasicLead":{"type":"object","properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"company":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]}},"required":["id","name","first_name","last_name","company","linkedin_url"]},"CampaignLeadSender":{"type":"object","properties":{"id":{"type":["string","null"]},"profile_name":{"type":["string","null"]},"status":{"type":["string","null"]}},"required":["id","profile_name","status"]},"CampaignLeadCurrentState":{"type":"object","additionalProperties":false,"properties":{"connection_status":{"type":["string","null"],"enum":["connected","sent",null]},"inmail_status":{"type":["string","null"],"enum":["sent","replied",null]},"message_status":{"type":["string","null"],"enum":["sent","replied",null]},"last_action_at":{"type":["string","null"],"format":"date-time"}},"required":["last_action_at"]},"CampaignLeadActionEvent":{"type":"object","description":"A chronological campaign lead action.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["send_connection_request","send_connection_request_with_note","send_message","send_open_message","send_inmail","profile_viewed","like_post","follow_lead","comment_post","reply_comment"]},"status":{"type":"string","enum":["pending","scheduled","in_progress","sent","completed","failed","skipped","cancelled"]},"performed_at":{"type":"string","format":"date-time"},"scheduled_for":{"type":"string","format":"date-time"},"accepted_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true}},"required":["id","type","status","metadata"]},"CampaignLead":{"type":"object","properties":{"id":{"type":"string"},"campaign_id":{"type":"string"},"lead_id":{"type":["string","null"]},"current_state":{"$ref":"#/components/schemas/CampaignLeadCurrentState"},"lead":{"$ref":"#/components/schemas/CampaignLeadBasicLead"},"status":{"type":"string","enum":["queued","active","completed","failed","excluded","paused"]},"priority":{"type":"string","enum":["high","medium","low","unknown"]},"intent":{"type":["string","null"]},"intent_source":{"type":["string","null"]},"intent_reason":{"type":["string","null"]},"sender":{"anyOf":[{"$ref":"#/components/schemas/CampaignLeadSender"},{"type":"null"}]},"actions_performed":{"type":"array","items":{"$ref":"#/components/schemas/CampaignLeadActionEvent"}},"parked_reason":{"type":["string","null"]},"enrolled_at":{"type":"string","format":"date-time"},"next_action_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"required":["id","campaign_id","lead_id","current_state","lead","status","priority","intent","intent_source","intent_reason","sender","actions_performed","parked_reason","enrolled_at","next_action_at","completed_at"]},"CampaignLeadMessageOverrideInput":{"type":"object","additionalProperties":false,"properties":{"node_type":{"type":"string","enum":["send_message"],"description":"Campaign node type to override. Only send_message nodes are supported."},"message_stage":{"type":"string","enum":["ice_breaker","follow_up_1","follow_up_2"],"description":"Campaign message stage to override. ice_breaker = first message, follow_up_1 = second message, follow_up_2 = third message."},"message":{"type":"string","minLength":1,"maxLength":8000,"description":"Lead-level message text to send instead of AI generation or template fallback."}},"required":["node_type","message_stage","message"]},"CampaignLeadMessageOverride":{"type":"object","properties":{"id":{"type":"string"},"campaign_id":{"type":"string"},"lead_id":{"type":"string"},"node_type":{"type":"string","enum":["send_message"]},"message_stage":{"type":"string","enum":["ice_breaker","follow_up_1","follow_up_2"]},"message":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","campaign_id","lead_id","node_type","message_stage","message","updated_at"]},"CampaignLeadMessageOverrideResult":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignLeadMessageOverride"}},"lead_campaign_state":{"type":"string","enum":["enrolled","pending_enrollment"]}},"required":["data","lead_campaign_state"]},"CampaignActionRequest":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["start","pause","resume"],"description":"`start` starts a draft campaign, `pause` pauses an active campaign, and `resume` resumes a paused campaign."}},"required":["action"]},"CampaignActionResult":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}},"required":["data"]},"Campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","started","paused","completed"]},"totalLeads":{"type":"integer"},"connectionsSent":{"type":"integer"},"messagesSent":{"type":"integer"},"repliesReceived":{"type":"integer"},"connectionRequestsAccepted":{"type":"integer"},"linkedinAccounts":{"type":"array","items":{"$ref":"#/components/schemas/CampaignLinkedInAccount"}},"leadList":{"anyOf":[{"$ref":"#/components/schemas/CampaignLeadList"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","status","totalLeads","connectionsSent","messagesSent","repliesReceived","connectionRequestsAccepted","linkedinAccounts","leadList","createdAt","updatedAt"]},"LinkedInAccountSendingLimits":{"type":"object","properties":{"max_follows_per_day":{"type":"integer"},"max_messages_per_day":{"type":"integer"},"max_inmails_per_day":{"type":"integer"},"max_connection_requests_per_day":{"type":"integer"},"max_profile_views_per_day":{"type":"integer"},"max_post_likes_per_day":{"type":"integer"},"max_comments_per_day":{"type":"integer"},"warmup_enabled":{"type":"boolean"}},"required":["max_follows_per_day","max_messages_per_day","max_inmails_per_day","max_connection_requests_per_day","max_profile_views_per_day","max_post_likes_per_day","max_comments_per_day","warmup_enabled"]},"LinkedInAccount":{"type":"object","properties":{"id":{"type":"string"},"profile_name":{"type":["string","null"]},"profile_url":{"type":["string","null"]},"profile_picture_url":{"type":["string","null"]},"status":{"type":"string","enum":["connecting","connected","disconnected","error","awaiting_code"]},"account_tier":{"type":"string","enum":["regular","premium","sales_navigator"]},"sending_limits":{"$ref":"#/components/schemas/LinkedInAccountSendingLimits"},"connection_count":{"type":["integer","null"]},"pending_invite_count":{"type":["integer","null"]},"last_ran_at":{"type":["string","null"],"format":"date-time"},"cooldown_until":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","profile_name","profile_url","profile_picture_url","status","account_tier","sending_limits","connection_count","pending_invite_count","last_ran_at","cooldown_until","created_at","updated_at"]},"CompanyDetails":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"tagline":{"type":["string","null"]},"description":{"type":["string","null"]},"website":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"industry":{"type":["string","null"]},"employee_count":{"type":["integer","null"]},"employee_count_range_min":{"type":["integer","null"]},"employee_count_range_max":{"type":["integer","null"]},"hq_city":{"type":["string","null"]},"hq_country":{"type":["string","null"]},"founded_year":{"type":["integer","null"]},"specialties":{"type":["array","null"],"items":{"type":"string"}},"logo_url":{"type":["string","null"]},"follower_count":{"type":["integer","null"]},"company_type":{"type":["string","null"]},"phone":{"type":["string","null"]},"active":{"type":["boolean","null"]},"top_companies_rank":{"type":["integer","null"]},"top_companies_list_name":{"type":["string","null"]},"enriched_at":{"type":"string","format":"date-time"}},"required":["id","enriched_at"]},"LeadList":{"type":"object","properties":{"id":{"type":"string"},"workspace_name":{"type":["string","null"]},"name":{"type":"string"},"description":{"type":["string","null"]},"is_default":{"type":"boolean"},"created_by":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"lead_count":{"type":"integer"}},"required":["id","workspace_name","name","is_default","created_by","created_at","updated_at"]},"Lead":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"email":{"type":["string","null"]},"company":{"type":["string","null"]},"company_linkedin_url":{"type":["string","null"]},"job_title":{"type":["string","null"]},"headline":{"type":["string","null"]},"summary":{"type":["string","null"]},"industry":{"type":["string","null"]},"skills":{"type":["array","null"],"items":{"type":"string"}},"linkedin_url":{"type":["string","null"]},"phone":{"type":["string","null"]},"location":{"type":["string","null"]},"gender":{"type":["string","null"]},"date_of_birth":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]},"profile_picture_url":{"type":["string","null"]},"profile_enriched_at":{"type":["string","null"],"format":"date-time"},"company_enriched_at":{"type":["string","null"],"format":"date-time"},"enrichment_requested_at":{"type":["string","null"],"format":"date-time"},"company_details":{"anyOf":[{"$ref":"#/components/schemas/CompanyDetails"},{"type":"null"}]},"enrichment_failed":{"type":"boolean"},"lead_heat_reason":{"type":["string","null"]},"lead_heat_raw_score":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","created_at","updated_at"]},"LeadWithLists":{"allOf":[{"$ref":"#/components/schemas/Lead"},{"type":"object","properties":{"lead_list_ids":{"type":"array","items":{"type":"string"}}},"required":["lead_list_ids"]}]},"LeadCreateRequest":{"type":"object","additionalProperties":false,"required":["first_name","last_name","linkedin_url"],"properties":{"first_name":{"type":"string","minLength":1,"example":"First"},"last_name":{"type":"string","minLength":1,"example":"Prospect"},"email":{"type":["string","null"],"example":"first.prospect@example.com"},"company":{"type":["string","null"],"example":"Acme"},"company_linkedin_url":{"type":["string","null"],"example":"https://www.linkedin.com/company/acme"},"job_title":{"type":["string","null"],"example":"VP Sales"},"headline":{"type":["string","null"],"example":"VP Sales at Acme"},"summary":{"type":["string","null"],"example":"Revenue leader focused on enterprise growth."},"industry":{"type":["string","null"],"example":"Software"},"skills":{"type":["array","null"],"items":{"type":"string"},"example":["Sales","GTM"]},"linkedin_url":{"type":"string","example":"https://www.linkedin.com/in/first-prospect"},"phone":{"type":["string","null"],"example":"+1 415 555 0101"},"location":{"type":["string","null"],"example":"San Francisco, CA"},"gender":{"type":["string","null"],"example":"unknown"},"date_of_birth":{"type":["string","null"],"format":"date-time","example":"1990-01-15T00:00:00.000Z"},"notes":{"type":["string","null"],"example":"Met at SaaS Summit."},"profile_picture_url":{"type":["string","null"],"example":"https://example.com/first-prospect.jpg"}},"example":{"first_name":"First","last_name":"Prospect","email":"first.prospect@example.com","company":"Acme","company_linkedin_url":"https://www.linkedin.com/company/acme","job_title":"VP Sales","headline":"VP Sales at Acme","summary":"Revenue leader focused on enterprise growth.","industry":"Software","skills":["Sales","GTM"],"linkedin_url":"https://www.linkedin.com/in/first-prospect","phone":"+1 415 555 0101","location":"San Francisco, CA","gender":"unknown","date_of_birth":"1990-01-15T00:00:00.000Z","notes":"Met at SaaS Summit.","profile_picture_url":"https://example.com/first-prospect.jpg"}},"LeadListCreateInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":["string","null"],"maxLength":500}},"required":["name"],"additionalProperties":false},"LeadListCreateValidationError":{"type":"object","properties":{"index":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"]}}},"required":["index","errors"]},"LeadCreateValidationError":{"type":"object","properties":{"index":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}},"required":["field","message"]}}},"required":["index","errors"]},"LeadCreateProcessingError":{"type":"object","properties":{"index":{"type":"integer"},"error":{"type":"object","properties":{"code":{"type":"string","enum":["processing_failed"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["index","error"]},"LeadEnrichment":{"type":"object","properties":{"status":{"type":"string","enum":["already_enriched","enriched","failed","insufficient_credits"]},"charged":{"type":"boolean"},"credits_remaining":{"type":"integer"}},"required":["status","charged","credits_remaining"]},"ConversationLead":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]}},"required":["id","first_name","last_name","linkedin_url"]},"ConversationLinkedInAccount":{"type":"object","properties":{"id":{"type":"string"},"profile_name":{"type":["string","null"]}},"required":["id","profile_name"]},"ConversationLastMessage":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"direction":{"type":"string","enum":["sent","received"]}},"required":["id","content","sent_at","direction"]},"ConversationMessage":{"type":"object","properties":{"id":{"type":"string"},"linkedin_message_id":{"type":"string"},"content":{"type":"string"},"direction":{"type":"string","enum":["sent","received"]},"sent_at":{"type":"string","format":"date-time"},"content_type":{"type":"string","enum":["text"]}},"required":["id","linkedin_message_id","content","direction","sent_at","content_type"]},"SendConversationMessageRequest":{"type":"object","properties":{"content":{"type":"string","minLength":1,"maxLength":8000,"description":"Plain-text message body to send into the existing LinkedIn conversation."}},"required":["content"]},"SendConversationMessageResult":{"type":"object","properties":{"ok":{"type":"boolean"},"pending":{"type":"boolean","description":"True when LinkedIn accepted the send but did not return a message id immediately. The message will appear after the next inbox sync."},"message":{"anyOf":[{"$ref":"#/components/schemas/ConversationMessage"},{"type":"null"}]}},"required":["ok","pending","message"]},"Conversation":{"type":"object","properties":{"id":{"type":"string"},"linkedin_conversation_id":{"type":"string"},"intent":{"type":["string","null"],"enum":["INTERESTED","CURIOUS","NOT_INTERESTED","DEFERRED","NEEDS_LABEL","CONVERTED",null]},"is_unread":{"type":"boolean"},"lead":{"$ref":"#/components/schemas/ConversationLead"},"linkedin_account":{"$ref":"#/components/schemas/ConversationLinkedInAccount"},"last_message":{"anyOf":[{"$ref":"#/components/schemas/ConversationLastMessage"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","linkedin_conversation_id","intent","is_unread","lead","linkedin_account","last_message","created_at","updated_at"]},"ConversationDetail":{"type":"object","properties":{"id":{"type":"string"},"linkedin_conversation_id":{"type":"string"},"intent":{"type":["string","null"],"enum":["INTERESTED","CURIOUS","NOT_INTERESTED","DEFERRED","NEEDS_LABEL","CONVERTED",null]},"is_unread":{"type":"boolean"},"lead":{"$ref":"#/components/schemas/ConversationLead"},"linkedin_account":{"$ref":"#/components/schemas/ConversationLinkedInAccount"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ConversationMessage"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","linkedin_conversation_id","intent","is_unread","lead","linkedin_account","messages","created_at","updated_at"]}}},"paths":{"/campaigns":{"get":{"tags":["Campaigns"],"security":[{"bearerAuth":[]}],"summary":"List campaigns for the API key workspace","description":"Returns every outreach campaign in the API key workspace, newest first. Each campaign includes its lifecycle `status` (`draft`, `started`, `paused`, `completed`), aggregate performance metrics (total leads, connection requests sent and accepted, messages sent, replies received), the LinkedIn sender accounts assigned to it, and the source lead list when one is configured. Results are cursor-paginated (`limit` 1–500, default 100). Requires the `campaigns:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/campaigns/{campaign_id}/actions":{"post":{"tags":["Campaigns"],"security":[{"bearerAuth":[]}],"summary":"Run a campaign lifecycle action","description":"Starts, pauses, or resumes one campaign in the API key workspace using the same lifecycle boundaries as the campaign settings UI. `start` is only valid for draft campaigns and requires a configured lead list, schedule, LinkedIn sender account, valid LinkedIn sender session, and message setup; it enrolls every lead from the source lead list. `pause` is only valid for active campaigns. `resume` is only valid for paused campaigns and only flips the campaign back to active. Returns 404 when the campaign does not exist in the workspace and 409 when the requested action does not match the current campaign state. Requires the `campaigns:write` scope.","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"action":{"type":"string","enum":["start","pause","resume"]}},"required":["action"],"example":{"action":"start"}},"examples":{"start":{"summary":"Start a draft campaign","value":{"action":"start"}},"pause":{"summary":"Pause an active campaign","value":{"action":"pause"}},"resume":{"summary":"Resume a paused campaign","value":{"action":"resume"}}}}}},"responses":{"200":{"description":"Updated campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignActionResult"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/campaigns/{campaign_id}/leads":{"get":{"tags":["Campaigns"],"security":[{"bearerAuth":[]}],"summary":"List campaign leads with status-table fields","description":"Lists the leads enrolled in a campaign with the same fields shown in the campaign status table, newest enrollment first. Each row includes the lead's current funnel state (connection, InMail, and message status with the last-action timestamp), enrollment `status` and `priority`, reply `intent` and its source, the assigned LinkedIn sender, and a chronological `actions_performed` timeline of every action taken or scheduled for that lead. Cursor-paginated (`limit` 1–500, default 100). Returns 404 when the campaign does not exist in the API key workspace. Requires the `campaigns:read` scope.","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Campaign leads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CampaignLead"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/campaigns/{campaign_id}/leads/{lead_id}/message-overrides":{"put":{"tags":["Campaigns"],"security":[{"bearerAuth":[]}],"summary":"Save lead-level campaign message overrides","description":"Sets the exact text to send to one lead for specific message slots in a campaign, overriding both AI generation and the campaign's template fallback. Send 1–10 overrides in a single request; each is upserted by (`node_type`, `message_stage`), so repeating a call replaces the text previously saved for that slot.\n\nOnly `send_message` nodes can be overridden today, so `node_type` must be `send_message`. The `message_stage` selects which message in the sequence to override: `ice_breaker` (first message), `follow_up_1` (second), `follow_up_2` (third). Each message is capped at 8000 characters.\n\nThe campaign must contain a matching message slot for the supplied `node_type`/`message_stage`, otherwise the request returns 400. Overrides can be saved before the lead is enrolled: if the lead is already a campaign lead the response reports `lead_campaign_state: \"enrolled\"`; if it is not yet enrolled but belongs to the campaign's source lead list the override is stored for use at enrollment and the response reports `pending_enrollment`. If the lead is neither enrolled nor in the source lead list the request returns 409. Returns 404 when the campaign or lead does not exist in the workspace. Requires the `campaigns:write` scope.","parameters":[{"name":"campaign_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"lead_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"array","minItems":1,"maxItems":10,"items":{"$ref":"#/components/schemas/CampaignLeadMessageOverrideInput"},"example":[{"node_type":"send_message","message_stage":"ice_breaker","message":"Hi Rushabh, noticed ToolPioneers is helping teams automate outreach. Open to connecting?"},{"node_type":"send_message","message_stage":"follow_up_1","message":"Following up because teams like yours often need cleaner campaign operations before scaling outbound."},{"node_type":"send_message","message_stage":"follow_up_2","message":"Last note from me. Happy to share a concise workflow if outbound quality is a priority this quarter."}]}},"required":["messages"],"example":{"messages":[{"node_type":"send_message","message_stage":"ice_breaker","message":"Hi Rushabh, noticed ToolPioneers is helping teams automate outreach. Open to connecting?"},{"node_type":"send_message","message_stage":"follow_up_1","message":"Following up because teams like yours often need cleaner campaign operations before scaling outbound."},{"node_type":"send_message","message_stage":"follow_up_2","message":"Last note from me. Happy to share a concise workflow if outbound quality is a priority this quarter."}]}},"examples":{"message_sequence":{"summary":"Override a personalized message sequence","value":{"messages":[{"node_type":"send_message","message_stage":"ice_breaker","message":"Hi Rushabh, noticed ToolPioneers is helping teams automate outreach. Open to connecting?"},{"node_type":"send_message","message_stage":"follow_up_1","message":"Following up because teams like yours often need cleaner campaign operations before scaling outbound."},{"node_type":"send_message","message_stage":"follow_up_2","message":"Last note from me. Happy to share a concise workflow if outbound quality is a priority this quarter."}]}}}}}},"responses":{"200":{"description":"Saved message overrides","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignLeadMessageOverrideResult"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/linkedin_accounts":{"get":{"tags":["LinkedIn accounts"],"security":[{"bearerAuth":[]}],"summary":"List LinkedIn accounts for the API key workspace","description":"Lists the LinkedIn sender accounts connected to the API key workspace, newest first. Each account includes its connection `status` (`connecting`, `connected`, `disconnected`, `error`, `awaiting_code`), `account_tier` (`regular`, `premium`, `sales_navigator`), the configured daily sending limits and warm-up flag, current connection and pending-invite counts, and the last-run and cooldown timestamps. Cursor-paginated (`limit` 1–500, default 100). Requires the `linkedin_accounts:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"LinkedIn accounts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkedInAccount"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/lead_lists":{"get":{"tags":["Lead lists"],"security":[{"bearerAuth":[]}],"summary":"List lead lists for the API key workspace","description":"Lists every lead list in the API key workspace, newest first, each with its current member count. Cursor-paginated (`limit` 1–500, default 100). Requires the `lead_lists:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lead lists","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeadList"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Lead lists"],"security":[{"bearerAuth":[]}],"summary":"Create one or more lead lists for the API key workspace","description":"Creates one or more lead lists in the API key workspace from the `lead_lists` array. List names are made unique automatically — a name that collides with an existing list is suffixed (for example `Founders (Copy ...)`). The response returns the created lists in `data`, any rejected entries in `malformed`, and a `summary` of attempted/created/malformed counts. Returns 201 when every list was created and 207 when some entries were malformed but others succeeded. Requires the `lead_lists:write` scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lead_lists":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/LeadListCreateInput"}}},"required":["lead_lists"],"additionalProperties":false},"examples":{"batch":{"summary":"Create multiple lead lists","value":{"lead_lists":[{"name":"Founders","description":"Founder prospects"},{"name":"Operators","description":"Operations leaders"}]}}}}}},"responses":{"201":{"description":"Lead lists created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeadList"}},"malformed":{"type":"array","items":{"$ref":"#/components/schemas/LeadListCreateValidationError"}},"summary":{"type":"object","properties":{"attempted":{"type":"integer"},"created":{"type":"integer"},"malformed":{"type":"integer"}},"required":["attempted","created","malformed"]}},"required":["data","malformed","summary"]}}}},"207":{"description":"Some lead lists were created and some were malformed"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/lead_lists/{lead_list_id}":{"get":{"tags":["Lead lists"],"security":[{"bearerAuth":[]}],"summary":"Get a lead list from the API key workspace","description":"Returns a single lead list in the API key workspace, including its current member count. Returns 404 when the list does not exist in the workspace. Requires the `lead_lists:read` scope.","parameters":[{"name":"lead_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lead list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadList"}},"required":["data"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/lead_lists/{lead_list_id}/leads":{"get":{"tags":["Leads"],"security":[{"bearerAuth":[]}],"summary":"List leads in a lead list from the API key workspace","description":"Lists the leads that are members of a specific lead list, newest membership first, each with enriched company details plus lead heat score and reason when available. Cursor-paginated (`limit` 1–500, default 100). Returns 404 when the list does not exist in the API key workspace. Requires the `leads:read` scope.","parameters":[{"name":"lead_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Leads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}},"post":{"tags":["Leads"],"security":[{"bearerAuth":[]}],"summary":"Create one or more leads in a lead list","description":"Imports leads into a lead list. Accepts either a single lead object or a batch via the `leads` array (up to 100 per request). Leads are de-duplicated against the workspace, and each result is reported as `created` (a new lead was created and added), `added_existing` (an existing workspace lead was added to this list), or `already_in_list` (the lead was already a member).\n\nFor a single-lead request the response is the lead plus its `result`, returning 200 when the lead was `already_in_list` and 201 otherwise. For a batch request the response includes per-item `data`, `malformed` entries that failed validation, `failed` entries that errored during processing, and a `summary`; the status is 201 when leads were created or attached with no problems, 207 when some entries were malformed or failed, and 200 when nothing new was added. Returns 404 when the list does not exist in the workspace. Requires the `leads:write` scope.","parameters":[{"name":"lead_list_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LeadCreateRequest"},{"type":"object","properties":{"leads":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/LeadCreateRequest"},"example":[{"first_name":"First","last_name":"Prospect","email":"first.prospect@example.com","company":"Acme","company_linkedin_url":"https://www.linkedin.com/company/acme","job_title":"VP Sales","headline":"VP Sales at Acme","summary":"Revenue leader focused on enterprise growth.","industry":"Software","skills":["Sales","GTM"],"linkedin_url":"https://www.linkedin.com/in/first-prospect","phone":"+1 415 555 0101","location":"San Francisco, CA","gender":"unknown","date_of_birth":"1990-01-15T00:00:00.000Z","notes":"Met at SaaS Summit.","profile_picture_url":"https://example.com/first-prospect.jpg"},{"first_name":"Second","last_name":"Prospect","email":"second.prospect@example.com","company":"Globex","company_linkedin_url":"https://www.linkedin.com/company/globex","job_title":"Head of Operations","headline":"Head of Operations at Globex","summary":"Operations leader scaling global teams.","industry":"Manufacturing","skills":["Operations","Process improvement"],"linkedin_url":"https://www.linkedin.com/in/second-prospect","phone":"+1 212 555 0102","location":"New York, NY","gender":"unknown","date_of_birth":"1988-06-20T00:00:00.000Z","notes":"Requested follow-up after webinar.","profile_picture_url":"https://example.com/second-prospect.jpg"}]}},"required":["leads"],"additionalProperties":false,"example":{"leads":[{"first_name":"First","last_name":"Prospect","email":"first.prospect@example.com","company":"Acme","company_linkedin_url":"https://www.linkedin.com/company/acme","job_title":"VP Sales","headline":"VP Sales at Acme","summary":"Revenue leader focused on enterprise growth.","industry":"Software","skills":["Sales","GTM"],"linkedin_url":"https://www.linkedin.com/in/first-prospect","phone":"+1 415 555 0101","location":"San Francisco, CA","gender":"unknown","date_of_birth":"1990-01-15T00:00:00.000Z","notes":"Met at SaaS Summit.","profile_picture_url":"https://example.com/first-prospect.jpg"},{"first_name":"Second","last_name":"Prospect","email":"second.prospect@example.com","company":"Globex","company_linkedin_url":"https://www.linkedin.com/company/globex","job_title":"Head of Operations","headline":"Head of Operations at Globex","summary":"Operations leader scaling global teams.","industry":"Manufacturing","skills":["Operations","Process improvement"],"linkedin_url":"https://www.linkedin.com/in/second-prospect","phone":"+1 212 555 0102","location":"New York, NY","gender":"unknown","date_of_birth":"1988-06-20T00:00:00.000Z","notes":"Requested follow-up after webinar.","profile_picture_url":"https://example.com/second-prospect.jpg"}]}}]},"examples":{"single":{"summary":"Import one lead","value":{"first_name":"First","last_name":"Prospect","email":"first.prospect@example.com","company":"Acme","company_linkedin_url":"https://www.linkedin.com/company/acme","job_title":"VP Sales","headline":"VP Sales at Acme","summary":"Revenue leader focused on enterprise growth.","industry":"Software","skills":["Sales","GTM"],"linkedin_url":"https://www.linkedin.com/in/first-prospect","phone":"+1 415 555 0101","location":"San Francisco, CA","gender":"unknown","date_of_birth":"1990-01-15T00:00:00.000Z","notes":"Met at SaaS Summit.","profile_picture_url":"https://example.com/first-prospect.jpg"}},"batch":{"summary":"Import multiple leads","value":{"leads":[{"first_name":"First","last_name":"Prospect","email":"first.prospect@example.com","company":"Acme","company_linkedin_url":"https://www.linkedin.com/company/acme","job_title":"VP Sales","headline":"VP Sales at Acme","summary":"Revenue leader focused on enterprise growth.","industry":"Software","skills":["Sales","GTM"],"linkedin_url":"https://www.linkedin.com/in/first-prospect","phone":"+1 415 555 0101","location":"San Francisco, CA","gender":"unknown","date_of_birth":"1990-01-15T00:00:00.000Z","notes":"Met at SaaS Summit.","profile_picture_url":"https://example.com/first-prospect.jpg"},{"first_name":"Second","last_name":"Prospect","email":"second.prospect@example.com","company":"Globex","company_linkedin_url":"https://www.linkedin.com/company/globex","job_title":"Head of Operations","headline":"Head of Operations at Globex","summary":"Operations leader scaling global teams.","industry":"Manufacturing","skills":["Operations","Process improvement"],"linkedin_url":"https://www.linkedin.com/in/second-prospect","phone":"+1 212 555 0102","location":"New York, NY","gender":"unknown","date_of_birth":"1988-06-20T00:00:00.000Z","notes":"Requested follow-up after webinar.","profile_picture_url":"https://example.com/second-prospect.jpg"}]}}}}}},"responses":{"200":{"description":"Lead already belonged to the lead list","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"},"result":{"type":"string","enum":["already_in_list"]}},"required":["data","result"]},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"result":{"type":"string","enum":["already_in_list"]},"lead":{"$ref":"#/components/schemas/Lead"}},"required":["index","result","lead"]}},"malformed":{"type":"array","items":{"$ref":"#/components/schemas/LeadCreateValidationError"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/LeadCreateProcessingError"}},"summary":{"type":"object","properties":{"attempted":{"type":"integer"},"created":{"type":"integer"},"added_existing":{"type":"integer"},"already_in_list":{"type":"integer"},"malformed":{"type":"integer"},"failed":{"type":"integer"}},"required":["attempted","created","added_existing","already_in_list","malformed","failed"]}},"required":["data","malformed","failed","summary"]}]}}}},"201":{"description":"Lead created or existing lead attached to the lead list","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"},"result":{"type":"string","enum":["created","added_existing"]}},"required":["data","result"]},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"result":{"type":"string","enum":["created","added_existing","already_in_list"]},"lead":{"$ref":"#/components/schemas/Lead"}},"required":["index","result","lead"]}},"malformed":{"type":"array","items":{"$ref":"#/components/schemas/LeadCreateValidationError"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/LeadCreateProcessingError"}},"summary":{"type":"object","properties":{"attempted":{"type":"integer"},"created":{"type":"integer"},"added_existing":{"type":"integer"},"already_in_list":{"type":"integer"},"malformed":{"type":"integer"},"failed":{"type":"integer"}},"required":["attempted","created","added_existing","already_in_list","malformed","failed"]}},"required":["data","malformed","failed","summary"]}]}}}},"207":{"description":"Some leads were created or attached and some were malformed or failed to process","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"result":{"type":"string","enum":["created","added_existing","already_in_list"]},"lead":{"$ref":"#/components/schemas/Lead"}},"required":["index","result","lead"]}},"malformed":{"type":"array","items":{"$ref":"#/components/schemas/LeadCreateValidationError"}},"failed":{"type":"array","items":{"$ref":"#/components/schemas/LeadCreateProcessingError"}},"summary":{"type":"object","properties":{"attempted":{"type":"integer"},"created":{"type":"integer"},"added_existing":{"type":"integer"},"already_in_list":{"type":"integer"},"malformed":{"type":"integer"},"failed":{"type":"integer"}},"required":["attempted","created","added_existing","already_in_list","malformed","failed"]}},"required":["data","malformed","failed","summary"]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/leads":{"get":{"tags":["Leads"],"security":[{"bearerAuth":[]}],"summary":"List all leads for the API key workspace","description":"Lists every lead in the API key workspace, newest first, each with enriched company details, the IDs of the lead lists it belongs to, plus lead heat score and reason when available. Pass `query` to full-text search across first name, last name, company, job title, location, and email (space-separated terms are AND-matched, case-insensitive). Pass `list_ids` (comma-separated lead list IDs) to return only leads that belong to those lists. Cursor-paginated (`limit` 1–500, default 100). Requires the `leads:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"list_ids","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated lead list IDs to filter by."}}],"responses":{"200":{"description":"Leads","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeadWithLists"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/leads/{lead_id}":{"get":{"tags":["Leads"],"security":[{"bearerAuth":[]}],"summary":"Get a lead from the API key workspace","description":"Returns a single lead in the API key workspace, including enriched company details, the IDs of the lead lists it belongs to, plus lead heat score and reason when available. Returns 404 when the lead does not exist in the workspace. Requires the `leads:read` scope.","parameters":[{"name":"lead_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lead","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/LeadWithLists"}},"required":["data"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/leads/{lead_id}/enrich":{"post":{"tags":["Leads"],"security":[{"bearerAuth":[]}],"summary":"Enrich Lead Profile","description":"Enriches a lead's profile and company details from the enrichment provider. The `enrichment.status` reports the outcome: `enriched` (newly enriched), `already_enriched` (returned existing data without re-charging), `insufficient_credits` (not enough credits to enrich), or `failed` (the provider could not enrich the lead). `charged` indicates whether a credit was consumed, and `credits_remaining` reports the workspace balance after the call. Returns 404 when the lead does not exist in the workspace and 502 when the enrichment provider errors. Requires the `leads:write` scope.","parameters":[{"name":"lead_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lead profile enrichment result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"},"enrichment":{"$ref":"#/components/schemas/LeadEnrichment"}},"required":["data","enrichment"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/conversations":{"get":{"tags":["Conversations"],"security":[{"bearerAuth":[]}],"summary":"List conversations for the API key workspace","description":"Lists LinkedIn conversations across the API key workspace, ordered by most recent message. Each conversation includes the associated lead, the LinkedIn sender account, the reply `intent` when one has been classified, an unread flag, and a preview of the latest message. Filter with `unread_only=true` to return only unread threads and `linkedin_account_id` to scope results to a single sender account. Cursor-paginated (`limit` 1–500, default 100). Requires the `conversations:read` scope.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"unread_only","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"linkedin_account_id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/conversations/{conversation_id}":{"get":{"tags":["Conversations"],"security":[{"bearerAuth":[]}],"summary":"Get a conversation and its messages","description":"Returns a single conversation with its message history in chronological order (oldest first), plus the associated lead, LinkedIn sender account, and reply `intent`. Messages are cursor-paginated (`limit` 1–500, default 100). Returns 404 when the conversation does not exist in the API key workspace. Requires the `conversations:read` scope.","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation messages","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConversationDetail"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data","pagination"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/conversations/{conversation_id}/messages":{"post":{"tags":["Conversations"],"security":[{"bearerAuth":[]}],"summary":"Send a message to a conversation","description":"Sends a plain-text message into an existing LinkedIn conversation through the workspace's automation sender (maximum 8000 characters). On success the response reports `ok: true`; `pending: true` means LinkedIn accepted the send but did not immediately return a message id, in which case the message will appear after the next inbox sync. Returns 404 when the conversation does not exist in the workspace, 502 when the send fails, and 503 when message sending is temporarily unavailable. Requires the `conversations:write` scope.","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendConversationMessageRequest"}}}},"responses":{"200":{"description":"Message send result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SendConversationMessageResult"}},"required":["data"]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}}}}