> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendpilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Leads

> Retrieve leads with optional filtering by campaign and status

## Request

<ParamField header="X-API-Key" type="string" required>
  Your API key
</ParamField>

<ParamField query="campaignId" type="string" required>
  Campaign ID to filter leads by (required)
</ParamField>

<ParamField query="status" type="string">
  Filter by lead status. Options: `PENDING`, `PROCESSING`, `CONNECTION_SENT`, `CONNECTION_ACCEPTED`, `MESSAGE_SENT`, `REPLY_RECEIVED`, `FOLLOWUP_SENT`, `BLOCKED`, `PROFILE_UNREACHABLE`, `RATE_LIMITED`, `FAILED`, `SUCCESS`, `UNSUBSCRIBED`, `IRRELEVANT`, `SKIPPED`, `DONE`, `MEETING_BOOKED`, `OPPORTUNITY`, `LIKED_POST`
</ParamField>

<ParamField query="full" type="boolean" default="false">
  Return full lead data including all dynamic fields. Set to `true` for complete data.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of items per page (max: 100)
</ParamField>

## Response

<ResponseField name="leads" type="array">
  Array of lead objects

  <Expandable title="Lead Object (Summary)">
    <ResponseField name="id" type="string">
      Unique lead identifier
    </ResponseField>

    <ResponseField name="linkedinUrl" type="string">
      LinkedIn profile URL of the lead
    </ResponseField>

    <ResponseField name="firstName" type="string">
      Lead's first name (if available)
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Lead's last name (if available)
    </ResponseField>

    <ResponseField name="company" type="string">
      Lead's company (if available)
    </ResponseField>

    <ResponseField name="title" type="string">
      Lead's job title (if available)
    </ResponseField>

    <ResponseField name="status" type="string">
      Current lead status
    </ResponseField>

    <ResponseField name="customLeadStatus" type="string">
      Custom lead status for CRM categorization: `LEAD`, `INTERESTED`, `MEETING_BOOKED`, `MEETING_COMPLETE_NOT_CLOSED`, `CLOSED`, `WRONG_PERSON`, `NOT_INTERESTED`, `NO_RESPONSE`
    </ResponseField>

    <ResponseField name="campaignId" type="string">
      The campaign this lead belongs to
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp when the lead was added
    </ResponseField>
  </Expandable>

  <Expandable title="Lead Object (Full - when full=true)">
    <ResponseField name="id" type="string">
      Unique lead identifier
    </ResponseField>

    <ResponseField name="linkedinUrl" type="string">
      LinkedIn profile URL
    </ResponseField>

    <ResponseField name="firstName" type="string">
      First name
    </ResponseField>

    <ResponseField name="lastName" type="string">
      Last name
    </ResponseField>

    <ResponseField name="company" type="string">
      Company name
    </ResponseField>

    <ResponseField name="title" type="string">
      Job title
    </ResponseField>

    <ResponseField name="email" type="string">
      Email address
    </ResponseField>

    <ResponseField name="location" type="string">
      Location
    </ResponseField>

    <ResponseField name="industry" type="string">
      Industry
    </ResponseField>

    <ResponseField name="about" type="string">
      Bio/about text
    </ResponseField>

    <ResponseField name="website" type="string">
      Website URL
    </ResponseField>

    <ResponseField name="profilePictureUrl" type="string">
      Profile picture URL
    </ResponseField>

    <ResponseField name="isPremium" type="boolean">
      Is premium LinkedIn account
    </ResponseField>

    <ResponseField name="isOpenProfile" type="boolean">
      Is open profile
    </ResponseField>

    <ResponseField name="connectionCount" type="integer">
      Number of connections
    </ResponseField>

    <ResponseField name="followerCount" type="integer">
      Number of followers
    </ResponseField>

    <ResponseField name="status" type="string">
      Current lead status
    </ResponseField>

    <ResponseField name="customLeadStatus" type="string">
      Custom lead status
    </ResponseField>

    <ResponseField name="campaignId" type="string">
      Campaign ID
    </ResponseField>

    <ResponseField name="data" type="object">
      All dynamic lead data including custom fields
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      When the lead was added
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      When the lead was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="Pagination Object">
    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Items per page
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of leads
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.sendpilot.ai/v1/leads?campaignId=camp_xyz789&status=CONNECTION_ACCEPTED" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.sendpilot.ai/v1/leads?campaignId=camp_xyz789&status=CONNECTION_ACCEPTED',
    {
      headers: {
        'X-API-Key': process.env.SENDPILOT_API_KEY
      }
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.sendpilot.ai/v1/leads',
      params={
          'campaignId': 'camp_xyz789',
          'status': 'CONNECTION_ACCEPTED'
      },
      headers={'X-API-Key': 'YOUR_API_KEY'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "leads": [
      {
        "id": "lead_abc123",
        "linkedinUrl": "https://www.linkedin.com/in/john-doe",
        "firstName": "John",
        "lastName": "Doe",
        "company": "TechCorp",
        "title": "VP of Engineering",
        "status": "CONNECTION_ACCEPTED",
        "customLeadStatus": "LEAD",
        "campaignId": "camp_xyz789",
        "createdAt": "2024-02-20T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 45,
      "totalPages": 1
    }
  }
  ```
</ResponseExample>

<Tip>
  Use `full=true` to get complete lead data including all enriched fields and custom data. This is useful when you need detailed information about leads.
</Tip>


## OpenAPI

````yaml GET /v1/leads
openapi: 3.0.0
info:
  title: SendPilot External API
  description: >
    The SendPilot API enables you to programmatically manage LinkedIn outreach
    campaigns,

    add leads, update lead statuses, send messages, and receive real-time
    webhook notifications.
  version: 1.0.0
  contact:
    name: SendPilot Support
    email: support@sendpilot.ai
    url: https://sendpilot.ai
servers:
  - url: https://api.sendpilot.ai
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Credits
    description: Credits and quota management
  - name: Campaigns
    description: Campaign management endpoints
  - name: Leads
    description: Lead management endpoints
  - name: Lead Database
    description: Lead Database search endpoints
  - name: Lead Extractor
    description: Lead extraction campaign endpoints
  - name: Inbox
    description: Direct messaging endpoints
paths:
  /v1/leads:
    get:
      tags:
        - Leads
      summary: List leads
      description: List leads with optional filtering by campaign and status
      operationId: listLeads
      parameters:
        - name: campaignId
          in: query
          description: Filter by campaign ID
          schema:
            type: string
        - name: status
          in: query
          description: Filter by lead status
          schema:
            type: string
            enum:
              - PENDING
              - CONNECTION_SENT
              - CONNECTION_ACCEPTED
              - MESSAGE_SENT
              - REPLY_RECEIVED
              - DONE
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          description: Items per page
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
      responses:
        '200':
          description: List of leads
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    LeadListResponse:
      type: object
      properties:
        leads:
          type: array
          items:
            $ref: '#/components/schemas/Lead'
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - leads
        - pagination
    Lead:
      type: object
      properties:
        id:
          type: string
        linkedinUrl:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - CONNECTION_SENT
            - CONNECTION_ACCEPTED
            - MESSAGE_SENT
            - REPLY_RECEIVED
            - DONE
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        campaignId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - linkedinUrl
        - status
        - campaignId
        - createdAt
        - updatedAt
    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
        totalPages:
          type: integer
      required:
        - total
        - page
        - limit
        - totalPages
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        error:
          type: string
        code:
          type: string
        message:
          type: string
      required:
        - statusCode
        - message
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication

````