{ "openapi": "3.1.0", "info": { "title": "Precept API", "description": "Precept API provides powerful, programmatic access to our AI-driven B2B account research, company enrichment, and verified contact data capabilities. Use these endpoints to discover high-intent companies, map decision-makers, and run personalized enrichment pipelines directly integrating with your CRM, spreadsheets, or automated workflows like Make and n8n.", "version": "1.0.0" }, "servers": [ { "url": "https://api.preceptai.co.uk" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/companies/insights": { "post": { "summary": "Get Company Insights", "description": "\n\nRetrieve detailed insights and enrichments for a list of companies.\n\nThis endpoint enriches a list of companies with comprehensive data. You provide a list of companies, identified by either their website or LinkedIn URL, and specify the desired enrichments. The results are delivered to the `webhookUrl` you provide.\n\nGet company-level insights, such as:\n- Number of employees (by department)\n- Names and LinkedIn profiles of employees\n- Funding raised\n- Revenue\n- Strategic initiatives at the company\n- Latest news\n- Top problems the company is facing right now\n- **+42** more datapoints.\n\nYou can also make custom queries about the company.\n\nTo associate your own internal identifiers with each company, use the customData field. This data will be returned to you in the webhook response, allowing you to easily map the enrichment results back to your system.", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInsightsRequest" }, "examples": { "default": { "summary": "A default example for retrieving company insights.", "value": { "webhookUrl": "https://your-site.com/webhook", "companies": [ { "companyWebsite": "https://www.preceptai.co.uk", "customData": { "id": "12345" } }, { "companyWebsite": "mywebsite.com", "companyLinkedin": "https://www.linkedin.com/company/mywebsite", "customData": { "id": "12345", "crm_id": "01234" } }, { "companyLinkedin": "https://www.linkedin.com/company/samplecompany" } ], "queries": [ "What is their tech stack?", "Do they use HubSpot?" ], "enrichments": { "type": "decision_makers", "departments": [ "engineering", "sales" ], "jobTitles": [ "Software Engineer" ], "includeContactDetails": true, "decisionMakersLimit": 10 } } } } } } }, "responses": { "202": { "description": "Request accepted. The enrichment is in progress. The response will vary based on whether all companies could be processed.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Company enrichment requests accepted and are being processed." }, "enrichment_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "properties": { "message": { "type": "string", "example": "Not enough credits to enrich all companies. 5 companies enrichment in progress. Please upgrade your plan to enrich all companies." }, "enrichment_id": { "type": "string", "format": "uuid" }, "skipped_companies": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyInput" } } } } ] } } } }, "400": { "description": "Invalid input, a required field is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 400 error response.", "value": { "error": "Invalid input, 'webhookUrl' is required." } } } } } }, "402": { "description": "Insufficient credits to process any companies.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 402 error response.", "value": { "message": "Not enough credits to start enrichment. Please upgrade your plan to start enrichment." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 500 error response.", "value": { "error": "Internal server error." } } } } } } } } }, "/v1/companies/search": { "post": { "summary": "Search Companies via Query", "description": "\n\nSearch and enrich companies using natural language queries.\n\nThis endpoint allows you to search for companies using natural language (e.g., \"SaaS companies in London with 50-200 employees\") and optionally enrich them with insights, decision makers, or custom queries.\n\nResults are delivered to the provided `webhookUrl`.", "tags": [ "Companies" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequest" }, "examples": { "default": { "summary": "Search for companies and find decision makers.", "value": { "query": "SaaS companies in the UK with 50-200 employees", "webhookUrl": "https://your-site.com/webhook", "enrichments": { "type": "decision_makers", "departments": [ "marketing" ], "jobTitles": [ "Head of Marketing" ], "includeContactDetails": true, "decisionMakersLimit": 5 } } } } } } }, "responses": { "202": { "description": "Request accepted. The search and enrichment are in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Company search job successfully created and is being processed." }, "enrichment_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/leads/enrich": { "post": { "summary": "Start Contacts Enrichment", "description": "\n\nEnrich your contacts using this endpoint.\n\nThis endpoint enriches a list of contacts with contact details and Personalized AI insights:\n- Verified email addresses.\n- Verified phone numbers.\n- Professional summary.\n- Top problems.\n- Internal strategic initiatives.\n- Public appearances.\n- Tailored outreach messages for email (PIPE framework) and LinkedIn (SHIP framework) via `generateMessage`.\n\nTo enrich a contact, you can provide either their LinkedIn profile URL or a combination of their first name, last name, and company name/domain. You can process up to 1,000 contacts in a single request.\n\nTo associate your own internal identifiers with each lead, use the customData field. This data will be returned to you in the webhook response, allowing you to easily map the enrichment results back to your system.\n\nTo receive the results, you must provide a `webhookUrl`.", "tags": [ "People" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsEnrichRequest" }, "examples": { "default": { "summary": "A default example for enriching a list of leads.", "value": { "name": "Q3 Lead List", "webhookUrl": "https://your-site.com/webhook", "leads": [ { "linkedinUrl": "https://linkedin.com/in/johndoe", "enrichType": [ "emails", "phones" ], "customData": { "contact_id": "lead_123" } }, { "firstName": "Jane", "lastName": "Smith", "companyName": "Precept AI", "enrichType": [ "emails" ], "customData": { "contact_id": "lead_456" } } ], "includeContactDetails": true, "interests": [ "Banking", "Insurance" ], "generateMessage": [ "email", "linkedin" ] } } } } } }, "responses": { "202": { "description": "Request accepted. The enrichment is in progress. The response will vary based on whether all leads could be processed.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Enrichment job successfully created and batches are being processed." }, "enrichment_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "properties": { "message": { "type": "string", "example": "Not enough credits to enrich all leads. 15 leads enrichment in progress. Please upgrade your plan to enrich all leads." }, "enrichment_id": { "type": "string", "format": "uuid" }, "skipped_leads": { "type": "array", "items": { "$ref": "#/components/schemas/LeadInput" } } } } ] } } } }, "400": { "description": "Bad Request - Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 400 error response.", "value": { "error": "Bad Request", "message": "Invalid input, please check the documentation." } } } } } }, "402": { "description": "Insufficient credits to process any leads.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 402 error response.", "value": { "message": "Not enough credits to start enrichment. Please upgrade your plan to start enrichment." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 500 error response.", "value": { "error": "Internal server error." } } } } } } } } }, "/v1/leads/search": { "post": { "summary": "Search People via Query", "description": "\n\nSearch and enrich leads using this endpoint.\n\nThis endpoint searches for contacts in bulk using natural language queries and can enrich them with contact details and Personalized AI insights:\n- Verified email addresses.\n- Verified phone numbers.\n- Professional summary.\n- Top problems.\n- Internal strategic initiatives.\n- Public appearances.\n\nYou can search for up to 1000 contacts in a single request by adjusting the limit parameter.\n\nTo receive the results, you must provide a `webhookUrl`.", "tags": [ "People" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsSearchRequest" }, "examples": { "default": { "summary": "A default example for searching leads.", "value": { "query": "Marketing heads at SaaS companies in California", "webhookUrl": "https://your-site.com/webhook", "limit": 50, "enrichType": [ "emails", "phones" ], "findInsights": true, "name": "California SaaS Marketing Heads", "includeContactDetails": false } }, "withPostInteractionSignal": { "summary": "Search leads with LinkedIn post interaction signal.", "value": { "query": "CTOs and VP Engineering in Fintech", "webhookUrl": "https://your-site.com/webhook", "limit": 30, "signal": { "type": "post_interaction", "keywords": ["fraud detection", "AML compliance"] }, "includeContactDetails": false } } } } } }, "responses": { "202": { "description": "Request accepted. The enrichment is in progress. The response will vary based on whether all leads could be processed.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "example": "Enrichment job successfully created and batches are being processed." }, "enrichment_id": { "type": "string", "format": "uuid" } } }, { "type": "object", "properties": { "message": { "type": "string", "example": "Not enough credits to enrich all leads. 15 leads enrichment in progress. Please upgrade your plan to enrich all leads." }, "enrichment_id": { "type": "string", "format": "uuid" }, "skipped_leads": { "type": "array", "items": { "$ref": "#/components/schemas/LeadInput" } } } } ] } } } }, "400": { "description": "Bad Request - Invalid input.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 400 error response.", "value": { "error": "Bad Request", "message": "Invalid input, please check the documentation." } } } } } }, "402": { "description": "Insufficient credits to process any leads.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 402 error response.", "value": { "message": "Not enough credits to start enrichment. Please upgrade your plan to start enrichment." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "default": { "summary": "Example of a 500 error response.", "value": { "error": "Internal server error." } } } } } } } } }, "/v1/leads/post-search": { "post": { "summary": "Discover People from LinkedIn Posts", "description": "\n\nDiscover leads directly from authors who recently published LinkedIn posts matching specific keywords.\n\nUnlike `/v1/leads/search` (which searches by persona query), this endpoint discovers leads directly from content authors without requiring a persona query or running LLM query analysis.\n\nEach result is one post author (a lead), not a raw post. Results are returned via `GET /v1/jobs/{jobId}` (or your webhook) and include the lead's profile fields (`full_name`, `first_name`, `last_name`, `job_title`, `company_name`, `company_domain`, `linkedin`, `user_name`, `location`, `country`, `connections_count`, `followers`, `enrich_email`, `enrich_phone`) plus a `post` object:\n\n- `url`: link to the LinkedIn post\n- `content`: post text (truncated to 2000 characters)\n- `posted_at`: when the post was published\n- `likes_count`: number of likes/reactions\n- `comments_count`: number of comments\n\nWith `findInsights: true`, results also include `summary`, `top_problems`, `internal_strategic_initiatives` and `public_appearances`.\n\nUse `sortBy: \"likes\"` or `sortBy: \"comments\"` to get the most-engaged posts instead of the default relevance order.\n\nOptionally enrich leads with verified contact details (emails/phones) and AI insights.", "tags": [ "People" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsPostSearchRequest" }, "examples": { "default": { "summary": "Example post search request", "value": { "keywords": [ "SEO problem", "struggling with SEO", "search rankings dropped" ], "timeframe": "month", "limit": 30, "name": "LinkedIn SEO problem posts", "includeContactDetails": false } }, "sortedByLikes": { "summary": "Most-liked posts from the past week", "value": { "keywords": [ "AI workflow", "marketing automation" ], "timeframe": "week", "sortBy": "likes", "limit": 30 } } } } } }, "responses": { "202": { "description": "Request accepted. Post search and enrichment is in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Lead search job successfully created and 30 leads are being processed." }, "enrichment_id": { "type": "string", "format": "uuid" } } } } } }, "400": { "description": "Bad Request. Invalid parameters or 'query'/'signal' provided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "402": { "description": "Insufficient credits to start post search.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/jobs/{jobId}": { "get": { "summary": "Get Job Status", "description": "\n\nRetrieve the current status and results of an enrichment or search job.\n\nUse this endpoint to poll the status of jobs initiated via endpoints that return an `enrichment_id`. The response payload will contain the enrichment progress or results when completed.", "tags": [ "Jobs" ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "description": "The unique identifier of the job.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The current status, progress or completed results of the job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enrichment_id": { "type": "string", "format": "uuid", "description": "The unique identifier for the job." }, "status": { "type": "string", "description": "Current status of the job (e.g., pending, completed)." }, "progress": { "type": "object", "description": "Progress metrics if the job is not yet completed.", "properties": { "completed": { "type": "integer" }, "total": { "type": "integer" }, "skipped": { "type": "integer" } } }, "results": { "type": "array", "description": "The array of enriched leads or company insights if the job is completed. Will be null if not yet completed.", "items": { "type": "object" } } } } } } }, "400": { "description": "Job ID is missing or invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: Access denied for the requested job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Job not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/credits": { "get": { "summary": "Get Remaining Credits", "description": "\n\nRetrieve the remaining credit balance for the authenticated user/organization.\n\nUse this endpoint to monitor your usage and programmatically check how many credits are available for search and enrichment requests.", "tags": [ "Billing" ], "responses": { "200": { "description": "The remaining credit balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "number", "description": "The remaining credit balance." } } }, "examples": { "default": { "summary": "Successful response", "value": { "credits": 2450.5 } } } } } }, "401": { "description": "Unauthorized: Missing or invalid API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/v1/campaigns": { "get": { "summary": "Get Campaign Metrics", "description": "\n\nRetrieve your LinkedIn outreach campaigns along with volume metrics, funnel counts, and acceptance/reply conversion rates.\n\n### Scope & API Key Requirements\n- **Personal / User Scope (`GET /v1/campaigns`)**: Requires a **User API key**. Returns campaigns and aggregated performance metrics for that user.\n- **Organization Scope (`GET /v1/campaigns?scope=org`)**: Requires an **Organization Service API key**. Aggregates campaigns across all seats in the organization, includes a `byUser` performance breakdown, and attributes each campaign by team member name and email.\n\nIf a User API key is used with `?scope=org`, or an Organization API key is used without `?scope=org`, the endpoint returns `403 Forbidden`.\n\n### Pagination & Rollup Behavior\n- **`summary` and `byUser` are never truncated by `limit`**: They always compute the complete totals across **all** campaigns and team members matching your `status` and `startDate`/`endDate` filters.\n- **`limit` and `offset` paginate the `campaigns` array**: When `scope=org`, campaigns from all team members are merged into a single chronological list sorted newest-first (`createdAt` descending), and `limit` controls how many campaign items are returned per page.", "tags": [ "Campaigns" ], "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "Reporting scope. Defaults to `user` (requires a personal User API key). Set to `org` to aggregate across all team members in the organization (requires an Organization API key).", "schema": { "type": "string", "enum": [ "user", "org" ], "default": "user" } }, { "name": "status", "in": "query", "required": false, "description": "Filter campaigns by status (`all`, `running`, `paused`, `queued`, `completed`, `stopped`, `archived`). Supports comma-separated values (e.g. `running,completed`).", "schema": { "type": "string", "default": "all" } }, { "name": "startDate", "in": "query", "required": false, "description": "Filter campaigns created on or after this date (ISO 8601 timestamp or `YYYY-MM-DD`).", "schema": { "type": "string", "example": "2026-10-01" } }, { "name": "endDate", "in": "query", "required": false, "description": "Filter campaigns created on or before this date (ISO 8601 timestamp or `YYYY-MM-DD`).", "schema": { "type": "string", "example": "2026-11-09" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of campaign items to return per page in the `campaigns` array (1 to 100, sorted newest-first). Does not limit `summary` or `byUser` totals.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset for the `campaigns` array (0 or greater).", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Campaign list, aggregate summary metrics, and conversion rates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "user", "organization" ], "description": "The resolved reporting scope." }, "timeframe": { "type": "object", "properties": { "startDate": { "type": "string", "nullable": true, "description": "Resolved ISO start date filter, or null for all-time." }, "endDate": { "type": "string", "nullable": true, "description": "Resolved ISO end date filter, or null for all-time." } } }, "summary": { "type": "object", "properties": { "totalCampaigns": { "type": "integer", "description": "Total number of campaigns matching the filter." }, "activeUsers": { "type": "integer", "description": "Number of team members with campaigns in the filtered period (only present when scope is `organization`)." }, "totalLeads": { "type": "integer", "description": "Total leads targeted across all matching campaigns." }, "totalInvited": { "type": "integer", "description": "Total connection requests sent." }, "totalAccepted": { "type": "integer", "description": "Total connection requests accepted." }, "overallAcceptanceRate": { "type": "number", "description": "Overall acceptance rate percentage (0 to 100)." }, "totalMessagesSent": { "type": "integer", "description": "Total follow-up messages sent." }, "totalReplies": { "type": "integer", "description": "Total replies received." }, "overallReplyRate": { "type": "number", "description": "Overall reply rate percentage (0 to 100)." } } }, "byUser": { "type": "array", "description": "Per-seat campaign performance breakdown (only included when `scope=org`).", "items": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "campaignCount": { "type": "integer" }, "totalLeads": { "type": "integer" }, "invitedCount": { "type": "integer" }, "acceptedCount": { "type": "integer" }, "acceptanceRate": { "type": "number" }, "messagesSentCount": { "type": "integer" }, "repliedCount": { "type": "integer" }, "replyRate": { "type": "number" } } } }, "campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "running", "paused", "queued", "completed", "stopped", "archived" ] }, "userName": { "type": "string", "description": "Team member name (included when `scope=org`)." }, "userEmail": { "type": "string", "description": "Team member email (included when `scope=org`)." }, "currentIndex": { "type": "integer" }, "totalLeads": { "type": "integer" }, "progressPct": { "type": "integer" }, "invitedCount": { "type": "integer" }, "acceptedCount": { "type": "integer" }, "acceptanceRate": { "type": "number", "description": "Percentage of invited leads who accepted the connection request." }, "messageSentCount": { "type": "integer" }, "repliedCount": { "type": "integer" }, "replyRate": { "type": "number", "description": "Percentage of messaged leads who replied." }, "createdAt": { "type": "string", "nullable": true }, "updatedAt": { "type": "string", "nullable": true }, "finishedAt": { "type": "integer", "nullable": true } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } } } } }, "examples": { "user_scope": { "summary": "User Scope Response (GET /v1/campaigns)", "value": { "scope": "user", "timeframe": { "startDate": "2026-10-01T00:00:00.000Z", "endDate": "2026-11-09T23:59:59.999Z" }, "summary": { "totalCampaigns": 8, "totalLeads": 400, "totalInvited": 350, "totalAccepted": 112, "overallAcceptanceRate": 32, "totalMessagesSent": 100, "totalReplies": 22, "overallReplyRate": 22 }, "campaigns": [ { "id": "camp_abc123", "name": "Fintech Decision Makers Q4", "status": "completed", "currentIndex": 50, "totalLeads": 50, "progressPct": 100, "invitedCount": 50, "acceptedCount": 18, "acceptanceRate": 36, "messageSentCount": 18, "repliedCount": 5, "replyRate": 27.8, "createdAt": "2026-11-02T14:30:00.000Z", "updatedAt": "2026-11-04T18:00:00.000Z", "finishedAt": 1793740200000 } ], "pagination": { "total": 8, "limit": 25, "offset": 0, "hasMore": false } } }, "organization_scope": { "summary": "Organization Scope Response (GET /v1/campaigns?scope=org)", "value": { "scope": "organization", "timeframe": { "startDate": "2026-10-01T00:00:00.000Z", "endDate": "2026-11-09T23:59:59.999Z" }, "summary": { "totalCampaigns": 14, "activeUsers": 2, "totalLeads": 700, "totalInvited": 580, "totalAccepted": 174, "overallAcceptanceRate": 30, "totalMessagesSent": 160, "totalReplies": 32, "overallReplyRate": 20 }, "byUser": [ { "name": "Alex Morgan", "email": "alex@acme.com", "campaignCount": 8, "totalLeads": 400, "invitedCount": 350, "acceptedCount": 112, "acceptanceRate": 32, "messagesSentCount": 100, "repliedCount": 22, "replyRate": 22 }, { "name": "Sarah Jenkins", "email": "sarah@acme.com", "campaignCount": 6, "totalLeads": 300, "invitedCount": 230, "acceptedCount": 62, "acceptanceRate": 27, "messagesSentCount": 60, "repliedCount": 10, "replyRate": 16.7 } ], "campaigns": [ { "id": "camp_9921", "name": "Fintech Decision Makers Q4", "status": "completed", "userName": "Alex Morgan", "userEmail": "alex@acme.com", "currentIndex": 50, "totalLeads": 50, "progressPct": 100, "invitedCount": 50, "acceptedCount": 18, "acceptanceRate": 36, "messageSentCount": 18, "repliedCount": 5, "replyRate": 27.8, "createdAt": "2026-11-02T14:30:00.000Z", "updatedAt": "2026-11-04T18:00:00.000Z", "finishedAt": 1793740200000 }, { "id": "camp_8840", "name": "Enterprise VP Sales UK", "status": "running", "userName": "Sarah Jenkins", "userEmail": "sarah@acme.com", "currentIndex": 20, "totalLeads": 50, "progressPct": 40, "invitedCount": 20, "acceptedCount": 7, "acceptanceRate": 35, "messageSentCount": 5, "repliedCount": 1, "replyRate": 20, "createdAt": "2026-11-01T09:15:00.000Z", "updatedAt": "2026-11-09T12:00:00.000Z", "finishedAt": null } ], "pagination": { "total": 14, "limit": 25, "offset": 0, "hasMore": false } } } } } } }, "400": { "description": "Invalid query parameter (`scope`, `status`, `startDate`, `endDate`, `limit`, or `offset`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "Unauthorized: Missing or invalid authorization header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "403": { "description": "Forbidden: Invalid API key, or API key type does not match the requested `scope`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "user_key_on_org_scope": { "summary": "User key used with ?scope=org", "value": { "error": "Forbidden: An organization API key is required to access organization-level campaigns. Your API key type is 'user'." } }, "org_key_on_user_scope": { "summary": "Org key used without ?scope=org", "value": { "error": "Forbidden: An organization API key cannot query personal user scope. Please provide a user API key, or add '?scope=org' to access organization campaigns." } } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } } }, "components": { "schemas": { "CompanyInput": { "type": "object", "properties": { "companyWebsite": { "type": "string", "format": "uri" }, "companyLinkedin": { "type": "string", "format": "uri" }, "customData": { "type": "object" } } }, "CompanyInsightsRequest": { "type": "object", "required": [ "companies" ], "properties": { "webhookUrl": { "type": "string", "format": "uri", "description": "Optional. The URL where the enrichment results will be sent via a POST request. If not provided, you can poll the GET /v1/jobs/{jobId} endpoint." }, "companies": { "type": "array", "description": "An array of company objects to enrich. You can process multiple companies in a single request. You must provide either the company website or LinkedIn URL. If providing a social URL, you must also include the company's name.", "items": { "type": "object", "required": [], "properties": { "companyName": { "type": "string", "description": "The name of the company." }, "companyWebsite": { "type": "string", "format": "uri", "description": "The official website of the company." }, "companyLinkedin": { "type": "string", "format": "uri", "description": "The official LinkedIn URL of the company." }, "customData": { "type": "object", "description": "An object for any custom data you want to associate with the company. This data will be returned with the enrichment results. Maximum of 5 properties allowed, and values must be strings with a maximum length of 100 characters.", "additionalProperties": { "type": "string" } } } } }, "queries": { "type": "array", "description": "A list of natural language questions to ask about the company.", "items": { "type": "string" } }, "enrichments": { "type": "object", "description": "An optional object to specify the desired enrichments. See the [Company Enrichments](/essentials/enrichments) guide for detailed descriptions and example responses for each type.", "properties": { "type": { "type": "string", "description": "The type of structured enrichment to perform. Enrichment types are broken down into three categories:\n\n| Category | Type | Explanation |\n| --- | --- | --- |\n| **Company-level** | `technology_stack` | Identifies the software, tools, and technologies used by the company. |\n| | `revenue` | Retrieves the estimated annual revenue of the company. |\n| | `recent_funding` | Provides details about the company's most recent funding rounds and investors. |\n| **Department-level** (Requires `departments` and/or `jobTitles`) | `employee_count` | Returns the total headcount within specified departments or job titles. |\n| | `employee_count_change` | Shows the growth or decline in employee headcount over time for specific roles. |\n| | `department_ratio` | Calculates the percentage of the company's total workforce that belongs to a specific department. |\n| | `job_posting_insights` | Analyzes active job postings and hiring trends for specified departments. |\n| **Lead-level** | `decision_makers` | Finds specific people based on the provided `departments` and/or `jobTitles`. The people are searched in the order of seniority, most senior employees are returned first. |\n| | `all_employees` | Fetches the company's entire employee directory. |", "enum": [ "decision_makers", "all_employees", "employee_count", "job_posting_insights", "department_ratio", "employee_count_change", "technology_stack", "revenue", "recent_funding" ] }, "departments": { "type": "array", "maxItems": 40, "description": "A list of department names to find employees or insights for. The department names are NOT case sensitive. Note: The combined total of departments and jobTitles cannot exceed 40.", "items": { "type": "string", "enum": [ "Actuary", "Administrative", "C-Suite", "Claims", "Consulting", "Customer Service", "Data & Analytics", "Design", "Education", "Engineering and Technical", "Finance & Accounting", "Founder", "Governance & Quality", "Health & Safety", "Human Resources", "Innovation", "Information Technology", "Legal", "Logistics", "Marketing", "Medical", "Operations", "Pricing", "Procurement & Sourcing", "Product", "Project Management", "Quality Control & Assurance", "Real Estate", "Research", "Risk & Compliance", "Sales", "Security", "Sustainability", "Trades", "Underwriting" ] } }, "jobTitles": { "type": "array", "maxItems": 40, "description": "A list of job titles to find employees for. You can use any job title (e.g., \"Software Engineer\", \"Sales Manager\"). Note: The combined total of departments and jobTitles cannot exceed 40.", "items": { "type": "string" } }, "country": { "type": "array", "items": { "type": "string" }, "description": "An optional array of countries to filter decision makers by (e.g., [\"United States\", \"United Kingdom\"]). This is only applicable for the `decision_makers` enrichment type." }, "includeContactDetails": { "type": "boolean", "description": "Whether to include contact details of the decision makers in the response. This is only applicable for the `decision_makers` enrichment type." }, "decisionMakersLimit": { "type": "integer", "description": "The maximum number of decision makers to return per company. Defaults to 5. This is only applicable for the `decision_makers` enrichment type." }, "limitType": { "type": "string", "enum": ["per_role", "overall"], "description": "Specifies how the limit is applied. If 'overall' (default), the limit applies as a total maximum across all specified roles combined. If 'per_role', it applies to each queried department/job title individually." } } } } }, "CompanySearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural language query to search for companies." }, "webhookUrl": { "type": "string", "format": "uri", "description": "Optional. Your webhook URL to receive the result of the company search operations. If not provided, you can poll the GET /v1/jobs/{jobId} endpoint." }, "limit": { "type": "integer", "maximum": 1000, "description": "Maximum number of companies to return (up to 1000)." }, "name": { "type": "string", "description": "A readable name for your enrichment job." }, "enrichments": { "type": "object", "description": "Optional enrichments to perform for each discovered company. See the [Company Enrichments](/essentials/enrichments) guide for detailed descriptions and example responses for each type.", "properties": { "type": { "type": "string", "description": "The type of structured enrichment to perform. Enrichment types are broken down into three categories:\n\n| Category | Type | Explanation |\n| --- | --- | --- |\n| **Company-level** | `technology_stack` | Identifies the software, tools, and technologies used by the company. |\n| | `revenue` | Retrieves the estimated annual revenue of the company. |\n| | `recent_funding` | Provides details about the company's most recent funding rounds and investors. |\n| **Department-level** (Requires `departments` and/or `jobTitles`)* | `employee_count` | Returns the total headcount within specified departments or job titles. |\n| | `employee_count_change` | Shows the growth or decline in employee headcount over time for specific roles. |\n| | `department_ratio` | Calculates the percentage of the company's total workforce that belongs to a specific department. |\n| | `job_posting_insights` | Analyzes active job postings and hiring trends for specified departments. |\n| **Lead-level** | `decision_makers` | Finds specific people based on the provided `departments` and/or `jobTitles`. The people are searched in the order of seniority, most senior employees are returned first. |\n| | `all_employees` | Fetches the company's entire employee directory. |", "enum": [ "decision_makers", "all_employees", "employee_count", "job_posting_insights", "department_ratio", "employee_count_change", "technology_stack", "revenue", "recent_funding" ] }, "departments": { "type": "array", "maxItems": 40, "description": "A list of department names to find employees or insights for. Note: The combined total of departments and jobTitles cannot exceed 40.", "items": { "type": "string" } }, "jobTitles": { "type": "array", "maxItems": 40, "description": "A list of job titles to find employees for. Note: The combined total of departments and jobTitles cannot exceed 40.", "items": { "type": "string" } }, "country": { "type": "array", "items": { "type": "string" } }, "includeContactDetails": { "type": "boolean" }, "decisionMakersLimit": { "type": "integer" }, "limitType": { "type": "string", "enum": ["per_role", "overall"] } } }, "queries": { "type": "array", "items": { "type": "string" } } } }, "CompanyInsightsWebhookPayload": { "type": "object", "properties": { "enrichment_id": { "type": "string", "format": "uuid" }, "results": { "type": "array", "items": { "type": "object", "properties": { "company_name": { "type": "string", "description": "Name of the company." }, "company_website": { "type": "string", "description": "Official website URL of the company." }, "company_linkedin": { "type": "string", "description": "LinkedIn company profile URL." }, "description": { "type": "string", "description": "Overview and description of the company." }, "size": { "type": "string", "description": "Company size range (e.g. '51-200 employees')." }, "employee_count": { "type": "integer", "description": "Estimated total number of employees." }, "location": { "type": "string", "description": "Headquarters address or location." }, "hq": { "type": "string", "description": "Headquarters city/state/country." }, "founded": { "type": "string", "description": "Year the company was founded." }, "industry": { "type": "string", "description": "Primary industry classification." }, "type": { "type": "string", "description": "Company ownership type (e.g. 'Privately Held', 'Public Company')." }, "followers": { "type": "integer", "description": "LinkedIn follower count." }, "logo_url": { "type": "string", "description": "URL to the company logo." }, "custom_data": { "type": "object" }, "decision_makers": { "type": "array", "items": { "type": "object" } }, "all_employees": { "type": "array", "items": { "type": "object" } }, "query_responses": { "type": "array", "items": { "type": "object" } }, "company_recent_funding": { "type": "string" }, "enrichment_errors": { "type": "object" } } } } } }, "LeadEnrichmentWebhookPayload": { "type": "object", "properties": { "enrichment_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "linkedinUrl": { "type": "string" }, "company_name": { "type": "string" }, "summary": { "type": "string", "description": "AI generated summary of the person" }, "top_problems": { "type": "string", "description": "AI generated top problems for the person/role" }, "internal_strategic_initiatives": { "type": "string", "description": "AI generated internal strategic initiatives" }, "public_appearances": { "type": "string", "description": "AI generated public appearances" }, "enrich_email": { "type": "string", "description": "The enriched email address if includeContactDetails is true" }, "enrich_phone": { "type": "string", "description": "The enriched phone number if includeContactDetails is true" }, "other_phones": { "type": "array", "items": { "type": "object" }, "description": "Other found phone numbers" }, "post_activity": { "type": "string", "description": "The title of the first LinkedIn post interaction that matched the search query (available when using signal type 'post_interaction'). See post_interactions for the full list with interaction type and date." }, "post_interactions": { "type": "array", "description": "Up to 5 LinkedIn post interactions that matched the search query (available when using signal type 'post_interaction').", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title/opening text of the LinkedIn post." }, "url": { "type": "string", "description": "The URL of the LinkedIn post." }, "action": { "type": "string", "description": "How the lead interacted with the post: 'like' (includes other reactions), 'comment' (includes replies to comments), 'share' (includes reposts) or 'post' (the lead authored it). Empty string if unknown." }, "activity_date": { "type": "string", "nullable": true, "description": "ISO 8601 timestamp of when the interaction was recorded in our data source. This is the date it was captured, not necessarily the exact time the lead interacted. Null if unavailable." } } } }, "post": { "type": "object", "description": "The LinkedIn post published by the lead (available when using signal type 'post_search').", "properties": { "url": { "type": "string", "description": "The URL of the LinkedIn post." }, "content": { "type": "string", "description": "The text content of the LinkedIn post." }, "posted_at": { "type": "string", "description": "The ISO timestamp of when the post was published." }, "likes_count": { "type": "integer", "description": "Number of reactions on the post." }, "comments_count": { "type": "integer", "description": "Number of comments on the post." } } }, "custom_data": { "type": "object" } } } }, "cost": { "type": "object", "description": "What the job charged, the same as GET /v1/jobs/{jobId} returns.", "properties": { "credits": { "type": "number", "description": "Total credits charged for the job." }, "breakdown": { "type": "array", "description": "Each charge: leads, leads_with_contact_found, insights, insights_with_contact_found, posts, post_activity, emails or phones.", "items": { "type": "object", "properties": { "item": { "type": "string" }, "count": { "type": "number" }, "credits": { "type": "number" } } } } } } } }, "LeadInput": { "type": "object", "properties": { "linkedinUrl": { "type": "string", "format": "uri" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "companyName": { "type": "string" }, "companyDomain": { "type": "string" }, "enrichType": { "type": "array", "items": { "type": "string", "enum": [ "emails", "phones" ] } }, "customData": { "type": "object" } } }, "LeadsEnrichRequest": { "type": "object", "required": [ "leads" ], "properties": { "findInsights": { "type": "boolean", "default": true, "description": "Generate AI insights (summary, top problems, strategic initiatives, public appearances) for each lead. On by default at +0.4 credits per lead. Set to false to skip them." }, "name": { "type": "string", "description": "A readable name for your enrichment for searching on your dashboard." }, "webhookUrl": { "type": "string", "format": "uri", "description": "Optional. Your webhook URL to receive the result of the enrichment. If not provided, you can poll the GET /v1/jobs/{jobId} endpoint." }, "leads": { "type": "array", "description": "An array of lead objects to enrich. Each object must contain either a `linkedinUrl` or a combination of `firstName`, `lastName`, and `companyName` or `companyDomain`.", "items": { "type": "object", "required": [], "properties": { "linkedinUrl": { "type": "string", "format": "uri", "description": "The LinkedIn profile URL of the contact." }, "firstName": { "type": "string", "description": "The first name of the contact." }, "lastName": { "type": "string", "description": "The last name of the contact." }, "companyName": { "type": "string", "description": "The name of the company where the contact works." }, "companyDomain": { "type": "string", "description": "The domain of the company." }, "enrichType": { "type": "array", "description": "The type of data to find. If not provided, both emails and phones will be found.", "items": { "type": "string", "enum": [ "emails", "phones" ] } }, "customData": { "type": "object", "description": "An object for any custom data you want to associate with the lead. This data will be returned with the enrichment results. Maximum of 5 properties allowed, and values must be strings with a maximum length of 100 characters." } } } }, "includeContactDetails": { "type": "boolean", "description": "Whether to include contact details (email and phone) for the enriched leads. If true, the webhook results will map back these fields as `enrichEmail` and `enrichPhone`." }, "translate": { "type": "boolean", "description": "This should be set to true if the lead names are not in English. This is needed for non english names to ensure the most accurate contact details are returned. The names will be translated to English before enriching them." }, "streamingResults": { "type": "boolean", "description": "Optional. When true and a `webhookUrl` is provided, contact results are progressively streamed in real-time as each lead is enriched (with `status: \"in_progress\"`), followed by a final completion webhook when all leads finish." }, "interests": { "type": "array", "maxItems": 5, "items": { "type": "string" }, "description": "Optional array of up to 5 keyword interests for the batch (e.g. ['Banking', 'Insurance']). Precept researches each lead regarding these interests and appends verified findings as '[ Interest]: ...' paragraphs to their professional summary." }, "generateMessage": { "type": "array", "items": { "type": "string", "enum": [ "email", "linkedin" ] }, "description": "Optional array of outreach channels to generate tailored messages for (e.g. ['email'], ['linkedin'], or ['email', 'linkedin']). Precept generates high-converting, personalized outreach copy using the PIPE framework for email (< 70 words, concise subject) and the SHIP framework for LinkedIn. Messages are returned in the webhook results or polling response." } } }, "LeadsSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Natural language query to search for leads (e.g. 'Software architects at tech companies in London')." }, "webhookUrl": { "type": "string", "format": "uri", "description": "Optional. Your webhook URL to receive the result of the lead search operations. If not provided, you can poll the GET /v1/jobs/{jobId} endpoint." }, "limit": { "type": "integer", "maximum": 1000, "description": "Maximum number of leads to return (up to 1000)." }, "enrichType": { "type": "array", "description": "The type of data to find. Possible values: `emails`, `phones`.", "items": { "type": "string", "enum": [ "emails", "phones" ] } }, "findInsights": { "type": "boolean", "description": "Generate AI insights (summary, top problems, strategic initiatives, public appearances) for each lead. Charges 1.4 credits per lead if true, else 1 credit." }, "name": { "type": "string", "description": "A readable name for your enrichment job for searching on your dashboard." }, "includeContactDetails": { "type": "boolean", "description": "Whether to include contact details (email and phone) for the discovered leads. If true, the webhook results will map back these fields as `enrich_email` and `enrich_phone`." }, "signal": { "type": "object", "description": "Optional LinkedIn activity signal for filtering persona search. Adds +0.5 credits per lead. Finds people matching your query who recently engaged (posted, liked, commented) with relevant content. (For post author discovery without persona query, use POST /v1/leads/post-search).", "required": [ "type", "keywords" ], "properties": { "type": { "type": "string", "enum": [ "post_interaction" ], "description": "Find people who recently engaged (posted, liked, commented) with LinkedIn posts matching keywords." }, "keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "description": "1 to 5 keywords or phrases to find engaged leads." } } }, "streamingResults": { "type": "boolean", "description": "Optional. When true and a `webhookUrl` is provided, contact results are progressively streamed in real-time as each lead is enriched (with `status: \"in_progress\"`), followed by a final completion webhook when all leads finish." } } }, "LeadsPostSearchRequest": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5, "description": "1 to 5 keywords or phrases to search LinkedIn posts for. Discovers leads directly from the authors of matching posts." }, "timeframe": { "type": "string", "enum": [ "day", "week", "month", "year" ], "default": "month", "description": "Timeframe of LinkedIn posts to search: 'day' (past 24h), 'week' (past 7 days), 'month' (past 30 days), or 'year'. Defaults to 'month'." }, "sortBy": { "type": "string", "enum": [ "relevance", "likes", "comments" ], "default": "relevance", "description": "How to rank matching posts. 'relevance' (default) keeps LinkedIn's relevance order. 'likes' or 'comments' selects the most-liked or most-commented posts from a larger candidate pool and returns results in descending order of that metric (ties broken by the other metric). Sorting is done by Precept, not by LinkedIn. No extra cost." }, "limit": { "type": "integer", "maximum": 1000, "default": 30, "description": "Maximum number of leads to return (up to 1000, default 30)." }, "name": { "type": "string", "description": "A readable name for your enrichment job for searching on your dashboard." }, "includeContactDetails": { "type": "boolean", "default": false, "description": "Whether to find and verify email addresses and phone numbers for discovered authors. Adds +3 credits for email, +10 for phone (or +13 for both) per person." }, "enrichType": { "type": "array", "description": "The type of contact details to find when includeContactDetails is true. Possible values: 'emails', 'phones'.", "items": { "type": "string", "enum": [ "emails", "phones" ] } }, "findInsights": { "type": "boolean", "default": false, "description": "Generate AI insights for each discovered lead. Charges 1.6 credits per lead if true, else 1.2 credits (both include 0.2 for the post)." }, "webhookUrl": { "type": "string", "format": "uri", "description": "Optional webhook URL to receive the result of the lead search operations." }, "streamingResults": { "type": "boolean", "default": false, "description": "Optional. When true and webhookUrl is provided, contact results are progressively streamed." } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } } }