> ## Documentation Index > Fetch the complete documentation index at: https://docs.parallellabs.app/llms.txt > Use this file to discover all available pages before exploring further. # Search for people by name, email, or phone across every source in one call. > Resolves matches through the identity graph, so records that belong to the same human are attributed to one person rather than returned as unrelated hits. Each per-source match carries the `personId` it resolved to, and the `people` array holds the resolved profiles. Falls back to a direct per-source scan for companies that have not yet built their identity graph (see POST /people/backfill). ## OpenAPI ````yaml https://api.parallellabs.app/docs/openapi.json get /api/v0/people/search openapi: 3.0.3 info: description: > # Introduction Welcome to the API. This API provides programmatic access to all platform features including AI agents, smart lists, documents, sequences, and media generation. ## Authentication The API supports two types of authentication: 1. **Company API Keys** - Scoped to a specific company 2. **Personal Access Keys** - User-level keys that work across all your companies --- ### Option 1: Company API Key Company API keys are tied to a specific company. Use this when you only need to access one company. **Getting a Company API Key:** 1. Log in to your dashboard 2. Navigate to **Integrations** page 3. Find the **API Keys** section and click **Generate New Key** 4. Copy and securely store your API key (it won't be shown again) **Usage:** Include your API key in the `X-API-Key` header: ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "X-API-Key: YOUR_COMPANY_API_KEY" \ -H "Content-Type: application/json" ``` Or use the `Authorization` header (OpenAI-compatible): ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "Authorization: Bearer YOUR_COMPANY_API_KEY" \ -H "Content-Type: application/json" ``` --- ### Option 2: Personal Access Key Personal access keys are tied to your user account and can access any company you belong to. Use this when you need to access multiple companies or build integrations that work across companies. **Getting a Personal Access Key:** 1. Log in to your dashboard 2. Click on your avatar/profile icon and go to **Profile** 3. Find the **Personal Access Keys** section 4. Click **Create New Key** 5. Give it a name and optionally set an expiration date 6. Copy and securely store your key (it won't be shown again) **Usage:** Personal access keys start with `pak_` and **require** you to specify which company to access using the `X-Company-ID` header: ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "Authorization: Bearer pak_your_personal_access_key" \ -H "X-Company-ID: your_company_id" \ -H "Content-Type: application/json" ``` Or using the `X-API-Key` header: ```bash curl -X GET "https://api.example.com/api/v0/agents" \ -H "X-API-Key: pak_your_personal_access_key" \ -H "X-Company-ID: your_company_id" \ -H "Content-Type: application/json" ``` You can also pass the company ID as a query parameter: ```bash curl -X GET "https://api.example.com/api/v0/agents?companyId=your_company_id" \ -H "Authorization: Bearer pak_your_personal_access_key" \ -H "Content-Type: application/json" ``` **Finding Your Company ID:** Your company ID can be found in the dashboard URL when viewing a company, or via the Settings page. --- ### Which Key Type Should I Use? | Use Case | Recommended Key Type | |----------|---------------------| | Single company integration | Company API Key | | Multi-company dashboard | Personal Access Key | | CI/CD pipelines | Company API Key | | Personal automation scripts | Personal Access Key | | Third-party app integration | Company API Key | --- ## Response Format All responses are returned in JSON format. Successful responses include the requested data: ```json { "id": "abc123", "name": "My Agent", "created": "2024-01-15T10:30:00Z" } ``` Error responses follow a consistent structure: ```json { "error": "Description of what went wrong" } ``` ## HTTP Status Codes | Code | Description | |------|-------------| | 200 | Success | | 201 | Created | | 400 | Bad Request - Invalid parameters | | 401 | Unauthorized - Invalid or missing API key | | 403 | Forbidden - Insufficient permissions | | 404 | Not Found - Resource doesn't exist | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Internal Server Error | ## Pagination List endpoints support pagination using `page` and `pageSize` parameters: ``` GET /api/v0/agents?page=1&pageSize=20 ``` Paginated responses include: - `items`: Array of results - `total`: Total number of items - `pages`: Total number of pages - `hasNext`: Whether more pages exist ## OpenAI Compatibility The Chat API (`/api/v0/chat/completions`) is fully compatible with the OpenAI API specification. --- ## MCP (Model Context Protocol) Integration The platform provides an MCP server that allows AI assistants like Claude Desktop, Cursor, Windsurf, and other MCP-compatible tools to interact with the full platform API. ### What is MCP? Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external tools and data sources. With MCP, your AI assistant can: - Browse and manage your AI agents - Create and monitor outreach sequences - Search your knowledge base documents - Generate AI content, images, audio, and video - Execute browser automation tasks - And access every other platform feature ### MCP Server URL ``` https://api.example.com/api/v0/mcp ``` This endpoint implements the **MCP Streamable HTTP Transport** (JSON-RPC 2.0) and is compatible with `mcp-remote` and other MCP clients. ### Available Tools The MCP server provides 3 tools that give access to the entire platform API: | Tool | Description | |------|-------------| | `platform_list_capabilities` | Browse available API endpoints by category (Agents, Sequences, Lists, Documents, etc.) | | `platform_get_action_details` | Get the full specification for an endpoint including required parameters | | `platform_execute_action` | Execute any API endpoint with automatic authentication | ### Connecting Claude Desktop 1. Open your Claude Desktop configuration file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the MCP server configuration: ```json { "mcpServers": { "platform": { "command": "npx", "args": ["-y", "mcp-remote", "https://api.example.com/api/v0/mcp"], "env": { "API_KEY": "your_api_key_here" } } } } ``` 3. Restart Claude Desktop 4. You can now ask Claude to interact with your platform data, for example: - "List my AI agents" - "Show me my active sequences" - "Create a new email sequence for cold outreach" - "Search my documents for pricing information" ### Connecting Cursor / Windsurf 1. Open Settings and navigate to the MCP section 2. Add a new MCP server with: - **URL**: `https://api.example.com/api/v0/mcp` - **Authentication**: Bearer token with your API key 3. The platform tools will now be available in your AI assistant ### Connecting via mcp-remote (Generic) For any MCP-compatible client, you can use the `mcp-remote` package: ```bash npx mcp-remote https://api.example.com/api/v0/mcp --header "Authorization: Bearer YOUR_API_KEY" ``` ### Authentication for MCP MCP requests use the same authentication as the REST API: **Using Company API Key:** ``` Authorization: Bearer YOUR_COMPANY_API_KEY ``` **Using Personal Access Key:** ``` Authorization: Bearer pak_your_personal_access_key X-Company-ID: your_company_id ``` ### Example MCP Interactions **List available capabilities:** ```json { "name": "platform_list_capabilities", "arguments": { "category": "Sequences" } } ``` **Get action details:** ```json { "name": "platform_get_action_details", "arguments": { "operationId": "post_sequences.create_sequence" } } ``` **Execute an action:** ```json { "name": "platform_execute_action", "arguments": { "operationId": "get_agents.list_agents" } } ``` ### MCP Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/api/v0/mcp/info` | GET | Get MCP server information and capabilities | | `/api/v0/mcp/tools/list` | GET | List all available MCP tools | | `/api/v0/mcp/tools/call` | POST | Execute an MCP tool call | title: API Documentation version: 1.0.0 servers: - url: https://api.parallellabs.app security: - CompanyApiKey: [] - BearerAuth: [] CompanyId: [] tags: - description: >- Create, manage, and interact with AI agents that handle customer interactions across multiple channels including website chat, email, SMS, and voice. name: Agents - description: Generate text-to-speech audio using ElevenLabs. name: Audio - description: Execute browser automation tasks with natural language. name: Browser - description: OpenAI-compatible chat completions API. name: Chat - description: >- Manage companies and workspaces. Each company has its own agents, lists, sequences, and other resources. name: Companies - description: Manage team members and their access to companies. name: Company Users - description: >- AI content engine for generating and scheduling social media posts, articles, and marketing content. name: Content - description: >- SEO/AEO opportunity engine. Analyzes a domain against its competitors, search results, and AI assistant answers (ChatGPT, Google AI) to surface scored content opportunities, each with search volumes and a ready-to-generate brief. Workflow: 1) Create a project per ideal customer profile with content_research_createResearchProject — each project researches one domain against one ICP, so separate audiences stay separated rather than being blended into one result set. 2) Start a run with content_research_runResearchProject (charges credits up front, not refunded on failure; only one run per project can be active at a time). 3) Poll content_research_listResearchRuns until the newest run reports completed or failed. 4) Read results with content_research_listOpportunities, scoped by projectId. 5) Act on one with content_research_generateFromOpportunity to write the piece, content_research_trackOpportunity to monitor its keywords, or content_research_dismissOpportunity to hide it. name: Content Research - description: Organize employees into departments for better team structure. name: Departments - description: >- Browse and search platform documentation. Workflow: 1) Call documentation_listDocumentationCategories to see the top-level categories. 2) Drill into one with documentation_listDocumentationPages?parentId={id} to see its child pages. 3) Call documentation_getDocumentationPage with a page id to read the full Markdown content. 4) Use documentation_searchDocumentation for keyword search across pages — it returns short snippets so you can decide which page to open in full. IMPORTANT: If the documentation you need does not exist or is incomplete after you browse and search, call documentation_submitDocumentationRequest to file a request so the docs team can add it. name: Documentation - description: Manage your knowledge base documents for AI training and reference. name: Documents - description: >- AI employees are customizable personas you can chat with. To chat with an employee: 1) Use platform_list_companies to find your company ID, 2) List employees with employees_listEmployeesApi or employees_getEmployees, 3) Chat using employees_chatEmployee with the employeeId and your message. name: Employees - description: Generate AI images using DALL-E, Leonardo, and other providers. name: Images - description: Manage incoming messages and communications across channels. name: Inbox - name: Integrations - description: Manage API keys for programmatic access to the platform. name: Keys - description: Create and manage landing pages for lead capture and campaigns. name: Landing Pages - description: >- Lead generation and contact enrichment. Generate leads from demographic/firmographic filters, premade intent segments, and buyer-intent keywords, and enrich a person or company from any identifiers (name, email, company, domain, LinkedIn URL). Workflow: 1) Call leads_listFieldOptions with describe=true to learn the filter surface, then re-call with field= or group= for valid enum values — never guess enum strings. 2) Call leads_searchSegments to find premade segment externalIds (e.g. "b2b_12636") for interest/intent targeting. 3) Call leads_generateLeads with filters, segment ids, and/or audience buyer-intent keywords to fetch leads. 4) Call leads_enrichContact to get full contact details (emails, phones, ~75 fields) for a specific person or company — prefer it over web search for contact lookups. 5) To keep the leads, call leads_importLeadsToList with the same criteria plus a destination listId: it builds the full audience and writes every matching contact into that smart list as rows. The list must already exist (create one with lists_saveList first), and the import runs in the background — it returns a taskId immediately. Generating leads costs 1 data credit per call and a matched enrichment costs 2; importing costs 1 per contact imported and is gated on the FULL match count (the whole audience is built regardless of how many rows you import), so check totalAvailable with leads_generateLeads before importing; the field-options and segments endpoints are free. name: Leads - description: Manage smart lists for organizing contacts and data. name: Lists - description: >- Create, schedule, and send one-shot marketing email campaigns to a smart list, and track open/click performance. name: Marketing Campaigns - description: >- Model Context Protocol (MCP) server for AI assistants like Claude Desktop, Cursor, and Windsurf. Provides tools for full platform API access. name: Mcp - description: >- Store and retrieve conversation context and user preferences for AI personalization. name: Memories - description: List available AI models. name: Models - description: >- Track keywords across social media platforms (Reddit, Hacker News, LinkedIn, X, Quora) and discover relevant conversations. Create monitors to track specific keywords, receive notifications when mentions are found, and generate AI-powered reply suggestions to engage with your audience. name: Monitors - name: Organizations - name: People - description: Organize work into projects for better task management. name: Projects - description: >- Manage automated outreach sequences for email, SMS, and multi-channel campaigns. name: Sequences - description: >- Create and manage support tickets, post follow-up messages on tickets, and track their status. name: Support - description: Organize and categorize resources with custom tags. name: Tags - description: Track API usage, credits, and billing information. name: Usage - description: Generate AI videos using fal.ai models. name: Video - description: Manage voice clones and text-to-speech voice options. name: Voices paths: /api/v0/people/search: get: tags: - People summary: >- Search for people by name, email, or phone across every source in one call. description: >- Resolves matches through the identity graph, so records that belong to the same human are attributed to one person rather than returned as unrelated hits. Each per-source match carries the `personId` it resolved to, and the `people` array holds the resolved profiles. Falls back to a direct per-source scan for companies that have not yet built their identity graph (see POST /people/backfill). operationId: people_peopleSearch parameters: - description: Name or email fragment to search for (case-insensitive substring) in: query name: query required: true schema: description: Name or email fragment to search for (case-insensitive substring) type: string - description: >- Company ID to scope the search. Required for PAK/API key auth; optional for JWT auth. in: query name: companyId required: false schema: description: >- Company ID to scope the search. Required for PAK/API key auth; optional for JWT auth. type: string - description: >- Max results per source (sequenceMembers, listRows, agentConversations, marketingCampaignRecipients). Default 50, max 200. in: query name: limit required: false schema: default: 50 description: >- Max results per source (sequenceMembers, listRows, agentConversations, marketingCampaignRecipients). Default 50, max 200. type: integer responses: '200': content: application/json: schema: description: Unified people search results properties: agentConversations: description: >- Matches from agent conversations (via contactInfo on AgentConversationV2) items: description: Agent conversation match properties: agentId: description: Parent agent ID type: string agentName: description: Parent agent name type: string channel: description: Conversation channel (website, email, sms, etc.) type: string contactEmail: description: Contact email from contactInfo type: string contactName: description: Contact name from contactInfo type: string contactPhone: description: Contact phone from contactInfo type: string conversationId: description: Agent conversation ID type: string lastActivityAt: description: Unix timestamp of last activity type: number sessionId: description: Session identifier on the conversation type: string status: description: Conversation status (active, ended, archived) type: string type: object type: array listRows: description: Matches from list rows items: description: List row match properties: listId: description: Parent list ID type: string listName: description: Parent list name type: string matchedColumn: description: Name of the column whose value matched the query type: string matchedValue: description: The value that matched (truncated to 500 chars) type: string rowId: description: List row ID type: string type: object type: array marketingCampaignRecipients: description: >- Matches from marketing campaign recipients (email match across every campaign in the company — no campaign ID required) items: description: >- Marketing campaign recipient match (full row + campaignName) properties: {} type: object type: array people: description: >- Resolved people matching the query. Each per-source match below carries the personId it resolved to, so matches across buckets can be attributed to the same human. Empty when the company has not yet built its identity graph, in which case the buckets fall back to a direct scan. items: description: A person resolved across every source in the company properties: city: description: City type: string companyName: description: Company name type: string country: description: Country type: string displayName: description: Best-known display name type: string email: description: Primary email (normalized) type: string firstName: description: First name type: string firstSeenDate: description: Earliest touchpoint (ISO 8601) type: string id: description: Person ID type: string identifiers: description: >- Every key resolving to this person (detail view only) items: description: Normalized identity key properties: tier: description: >- strong (email/phone/linkedin — uniquely identifies a person) or weak (name_company — may collide) type: string type: description: >- Key type: email, phone, linkedin, or name_company type: string value: description: >- The normalized key value (e.g. "+14155551234", not "(415) 555-1234") type: string type: object type: array jobTitle: description: Job title type: string lastName: description: Last name type: string lastSeenDate: description: Latest touchpoint (ISO 8601) type: string linkedinUrl: description: LinkedIn vanity slug type: string needsReview: description: >- True when a weak (name+company) key contributed to this profile and the merge should be confirmed type: boolean phone: description: Primary phone (E.164) type: string photoUrl: description: Company photo derived from the website at read time type: string sourceCounts: description: >- Touchpoint count per source type, e.g. {"sequence_member": 3} type: object state: description: State type: string touchpointCount: description: Total touchpoints across all sources type: integer website: description: Website type: string type: object type: array query: description: Echo of the search query type: string sequenceMembers: description: Matches from sequence members items: description: Sequence member match properties: email: description: Email type: string firstName: description: First name type: string lastName: description: Last name type: string memberId: description: Sequence member ID type: string phone: description: Phone type: string sequenceId: description: Parent sequence ID type: string sequenceName: description: Parent sequence name type: string status: description: >- Member status (active, unsubscribed, bounced, paused, removed) type: string type: object type: array type: object description: >- Unified people search results across sequences, lists, agent conversations, and campaigns '400': content: application/json: schema: $ref: '#/components/schemas/Error' description: Missing query '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Invalid credentials '500': content: application/json: schema: $ref: '#/components/schemas/Error' description: Server error components: schemas: Error: properties: error: description: Error message type: string type: object securitySchemes: CompanyApiKey: description: >- Company API key - scoped to a specific company. Generate from the Integrations page in your dashboard. in: header name: X-API-Key type: apiKey BearerAuth: description: >- Bearer token authentication. Can use either a Company API Key or a Personal Access Key (starting with pak_). Personal Access Keys require X-Company-ID header. scheme: bearer type: http CompanyId: description: >- Required when using Personal Access Keys. Specifies which company to access. in: header name: X-Company-ID type: apiKey ````