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

# List or get leads

> List leads across the workspace, narrowed by any filter, or pass `id` for one lead with its tags. `view` tags lists the tags in use; `view` export returns a CSV.



## OpenAPI

````yaml /openapi.json get /api/v1/public/leads
openapi: 3.1.0
info:
  description: >-
    Customer-facing API for managing outreach, leads, conversations, voice
    agents, knowledge bases, analytics, and webhooks.
  title: Sendora Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.sendora.ai
security: []
tags:
  - description: Leads, lead lists, importing, enriching and finding new prospects.
    name: Leads
  - description: Build, run and measure outreach, and enroll leads.
    name: Campaigns
  - description: Read and send messages, and manage who must not be contacted.
    name: Conversations
  - description: >-
      Voice and chat agents, their tools, knowledge bases, voices and website
      widgets.
    name: Agents
  - description: >-
      Start calls, and manage phone numbers, SMS registration, sending accounts
      and email domains.
    name: Calls and numbers
  - description: Webhooks, jobs, analytics and the Copilot assistant.
    name: Platform
  - description: Manage client workspaces, plans and branding.
    name: Agency
paths:
  /api/v1/public/leads:
    get:
      tags:
        - Leads
      summary: List or get leads
      description: >-
        List leads across the workspace, narrowed by any filter, or pass `id`
        for one lead with its tags. `view` tags lists the tags in use; `view`
        export returns a CSV.
      operationId: list_or_get_leads_api_v1_public_leads_get
      parameters:
        - description: Return this one lead, with its tags, instead of a list.
          in: query
          name: id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Return this one lead, with its tags, instead of a list.
            title: Id
        - description: >-
            leads is the list (the default). tags returns the tags in use.
            export returns leads as CSV text (one lead list with lead_list_id,
            up to 500 leads inline).
          in: query
          name: view
          required: false
          schema:
            default: leads
            description: >-
              leads is the list (the default). tags returns the tags in use.
              export returns leads as CSV text (one lead list with lead_list_id,
              up to 500 leads inline).
            enum:
              - leads
              - tags
              - export
            title: View
            type: string
        - description: >-
            Comma separated extras for a single lead: activities, and its
            context: ai_state, outreach_state (which channels are on),
            callbacks, campaigns, recordings.
          in: query
          name: include
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Comma separated extras for a single lead: activities, and its
              context: ai_state, outreach_state (which channels are on),
              callbacks, campaigns, recordings.
            title: Include
        - description: 'With include=activities: events to return, newest first.'
          in: query
          name: activities_limit
          required: false
          schema:
            default: 200
            description: 'With include=activities: events to return, newest first.'
            maximum: 500
            minimum: 1
            title: Activities Limit
            type: integer
        - description: >-
            With include=activities: only events older than this time. Use
            `activities_next_cursor` from the previous page.
          in: query
          name: activities_before
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              With include=activities: only events older than this time. Use
              `activities_next_cursor` from the previous page.
            title: Activities Before
        - description: Only leads in this lead list.
          in: query
          name: lead_list_id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Only leads in this lead list.
            title: Lead List Id
        - description: >-
            The campaign's id: the `id` from List or get campaigns. It is also
            the last part of that page's address in the app.
          in: query
          name: campaign_id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Only leads enrolled in this campaign.
            title: Campaign Id
        - description: Search by name, email, or company.
          in: query
          name: search
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Search by name, email, or company.
            title: Search
        - description: >-
            new, contacted, engaged, meeting_booked, meeting_scheduled,
            proposal_sent, closed_won or closed_lost.
          in: query
          name: pipeline_stage
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              new, contacted, engaged, meeting_booked, meeting_scheduled,
              proposal_sent, closed_won or closed_lost.
            title: Pipeline Stage
        - description: active, unsubscribed, bounced or dnc.
          in: query
          name: status
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: active, unsubscribed, bounced or dnc.
            title: Status
        - in: query
          name: page
          required: false
          schema:
            default: 1
            minimum: 1
            title: Page
            type: integer
        - in: query
          name: per_page
          required: false
          schema:
            default: 50
            maximum: 200
            minimum: 1
            title: Per Page
            type: integer
        - in: header
          name: X-API-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
        - in: header
          name: Authorization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      responses:
        '200':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PaginatedLeads'
                  - $ref: '#/components/schemas/LeadDetail'
                title: Response List Or Get Leads Api V1 Public Leads Get
          description: Successful Response
        '401':
          description: The X-API-Key header is missing, invalid, expired, or revoked.
        '402':
          description: >-
            The workspace is suspended for billing, or the request would exceed
            a plan or usage limit.
        '403':
          description: >-
            The key is valid but lacks the required scope, or the workspace has
            no active plan, lacks the entitlement, or has this feature turned
            off or view-only.
        '410':
          description: The workspace behind this key has been deleted.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          description: >-
            An unexpected Sendora error occurred. Retry only if the operation is
            safe to repeat.
        '503':
          description: >-
            An entitlement or billing check is temporarily unavailable. Retry
            after the Retry-After interval.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - label: cURL
          lang: bash
          source: >-
            curl -X GET 'https://api.sendora.ai/api/v1/public/leads' -H
            "X-API-Key: $SENDORA_API_KEY"
        - label: Python
          lang: python
          source: |-
            import requests

            url = 'https://api.sendora.ai/api/v1/public/leads'
            headers = {'X-API-Key': '$SENDORA_API_KEY'}
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            print(response.json())
        - label: JavaScript
          lang: javascript
          source: >-
            const response = await
            fetch("https://api.sendora.ai/api/v1/public/leads", {
              method: "GET",
              headers: { 'X-API-Key': process.env.SENDORA_API_KEY },
            });

            if (!response.ok) throw new Error(await response.text());

            console.log(await response.json());
        - label: Go
          lang: go
          source: >-
            req, err := http.NewRequest("GET",
            "https://api.sendora.ai/api/v1/public/leads", nil)

            if err != nil { log.Fatal(err) }

            req.Header.Set("X-API-Key", os.Getenv("SENDORA_API_KEY"))

            resp, err := http.DefaultClient.Do(req)

            if err != nil { log.Fatal(err) }

            defer resp.Body.Close()
components:
  schemas:
    PaginatedLeads:
      properties:
        items:
          description: Items returned by the Sendora API.
          items:
            $ref: '#/components/schemas/LeadOut'
          title: Items
          type: array
        page:
          description: Page returned by the Sendora API.
          title: Page
          type: integer
        per_page:
          description: Per page returned by the Sendora API.
          title: Per Page
          type: integer
        total:
          description: Total returned by the Sendora API.
          title: Total
          type: integer
      required:
        - items
        - total
        - page
        - per_page
      title: PaginatedLeads
      type: object
    LeadDetail:
      properties:
        activities:
          anyOf:
            - items:
                type: object
              type: array
            - type: 'null'
          description: Newest first. Present with include=activities.
          title: Activities
        automation_paused:
          default: false
          description: Automation paused returned by the Sendora API.
          title: Automation Paused
          type: boolean
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Avatar url returned by the Sendora API.
          title: Avatar Url
        city:
          anyOf:
            - type: string
            - type: 'null'
          description: City returned by the Sendora API.
          title: City
        company:
          anyOf:
            - type: string
            - type: 'null'
          description: Company returned by the Sendora API.
          title: Company
        company_domain:
          anyOf:
            - type: string
            - type: 'null'
          description: Company domain returned by the Sendora API.
          title: Company Domain
        company_profile:
          anyOf:
            - type: object
            - type: 'null'
          description: Company profile returned by the Sendora API.
          title: Company Profile
        country:
          anyOf:
            - type: string
            - type: 'null'
          description: Country returned by the Sendora API.
          title: Country
        created_at:
          description: Created at returned by the Sendora API.
          format: date-time
          title: Created At
          type: string
        current_campaign_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The campaign this lead is currently enrolled in: an `id` from List
            or get campaigns.
          title: Current Campaign Id
        custom_fields:
          anyOf:
            - type: object
            - type: 'null'
          description: Custom fields returned by the Sendora API.
          title: Custom Fields
        email:
          anyOf:
            - type: string
            - type: 'null'
          description: Email returned by the Sendora API.
          title: Email
        email_verification_score:
          anyOf:
            - type: integer
            - type: 'null'
          description: Email verification score returned by the Sendora API.
          title: Email Verification Score
        email_verification_status:
          anyOf:
            - type: string
            - type: 'null'
          description: Email verification status returned by the Sendora API.
          title: Email Verification Status
        email_verified_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Email verified at returned by the Sendora API.
          title: Email Verified At
        enrich_signals:
          anyOf:
            - type: object
            - type: 'null'
          description: Enrich signals returned by the Sendora API.
          title: Enrich Signals
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          description: First name returned by the Sendora API.
          title: First Name
        id:
          description: The lead's id. Pass it to any endpoint that takes `lead_id`.
          title: Id
          type: string
        industry:
          anyOf:
            - type: string
            - type: 'null'
          description: Industry returned by the Sendora API.
          title: Industry
        last_activity_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Last activity at returned by the Sendora API.
          title: Last Activity At
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Last name returned by the Sendora API.
          title: Last Name
        lead_list_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A lead list's id: the `id` from List or read lead collections (type
            list).
          title: Lead List Id
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Linkedin url returned by the Sendora API.
          title: Linkedin Url
        notes:
          anyOf:
            - type: string
            - type: 'null'
          description: Notes returned by the Sendora API.
          title: Notes
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          description: Phone number returned by the Sendora API.
          title: Phone Number
        pipeline_stage:
          anyOf:
            - type: string
            - type: 'null'
          description: Pipeline stage returned by the Sendora API.
          title: Pipeline Stage
        source:
          anyOf:
            - type: string
            - type: 'null'
          description: Source returned by the Sendora API.
          title: Source
        status:
          $ref: '#/components/schemas/LeadStatus'
          description: Status returned by the Sendora API.
        tags:
          description: The lead's tags.
          items:
            type: string
          title: Tags
          type: array
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: Title returned by the Sendora API.
          title: Title
        traffic_light_status:
          anyOf:
            - $ref: '#/components/schemas/TrafficLightStatus'
            - type: 'null'
          description: Traffic light status returned by the Sendora API.
        website:
          anyOf:
            - type: string
            - type: 'null'
          description: Website returned by the Sendora API.
          title: Website
      required:
        - id
        - status
        - created_at
      title: LeadDetail
      type: object
    HTTPValidationError:
      properties:
        detail:
          description: Detail returned by the Sendora API.
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      required: []
      title: HTTPValidationError
      type: object
    LeadOut:
      properties:
        automation_paused:
          default: false
          description: Automation paused returned by the Sendora API.
          title: Automation Paused
          type: boolean
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Avatar url returned by the Sendora API.
          title: Avatar Url
        city:
          anyOf:
            - type: string
            - type: 'null'
          description: City returned by the Sendora API.
          title: City
        company:
          anyOf:
            - type: string
            - type: 'null'
          description: Company returned by the Sendora API.
          title: Company
        company_domain:
          anyOf:
            - type: string
            - type: 'null'
          description: Company domain returned by the Sendora API.
          title: Company Domain
        company_profile:
          anyOf:
            - type: object
            - type: 'null'
          description: Company profile returned by the Sendora API.
          title: Company Profile
        country:
          anyOf:
            - type: string
            - type: 'null'
          description: Country returned by the Sendora API.
          title: Country
        created_at:
          description: Created at returned by the Sendora API.
          format: date-time
          title: Created At
          type: string
        current_campaign_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The campaign this lead is currently enrolled in: an `id` from List
            or get campaigns.
          title: Current Campaign Id
        custom_fields:
          anyOf:
            - type: object
            - type: 'null'
          description: Custom fields returned by the Sendora API.
          title: Custom Fields
        email:
          anyOf:
            - type: string
            - type: 'null'
          description: Email returned by the Sendora API.
          title: Email
        email_verification_score:
          anyOf:
            - type: integer
            - type: 'null'
          description: Email verification score returned by the Sendora API.
          title: Email Verification Score
        email_verification_status:
          anyOf:
            - type: string
            - type: 'null'
          description: Email verification status returned by the Sendora API.
          title: Email Verification Status
        email_verified_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Email verified at returned by the Sendora API.
          title: Email Verified At
        enrich_signals:
          anyOf:
            - type: object
            - type: 'null'
          description: Enrich signals returned by the Sendora API.
          title: Enrich Signals
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          description: First name returned by the Sendora API.
          title: First Name
        id:
          description: The lead's id. Pass it to any endpoint that takes `lead_id`.
          title: Id
          type: string
        industry:
          anyOf:
            - type: string
            - type: 'null'
          description: Industry returned by the Sendora API.
          title: Industry
        last_activity_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: Last activity at returned by the Sendora API.
          title: Last Activity At
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          description: Last name returned by the Sendora API.
          title: Last Name
        lead_list_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            A lead list's id: the `id` from List or read lead collections (type
            list).
          title: Lead List Id
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          description: Linkedin url returned by the Sendora API.
          title: Linkedin Url
        notes:
          anyOf:
            - type: string
            - type: 'null'
          description: Notes returned by the Sendora API.
          title: Notes
        phone_number:
          anyOf:
            - type: string
            - type: 'null'
          description: Phone number returned by the Sendora API.
          title: Phone Number
        pipeline_stage:
          anyOf:
            - type: string
            - type: 'null'
          description: Pipeline stage returned by the Sendora API.
          title: Pipeline Stage
        source:
          anyOf:
            - type: string
            - type: 'null'
          description: Source returned by the Sendora API.
          title: Source
        status:
          $ref: '#/components/schemas/LeadStatus'
          description: Status returned by the Sendora API.
        title:
          anyOf:
            - type: string
            - type: 'null'
          description: Title returned by the Sendora API.
          title: Title
        traffic_light_status:
          anyOf:
            - $ref: '#/components/schemas/TrafficLightStatus'
            - type: 'null'
          description: Traffic light status returned by the Sendora API.
        website:
          anyOf:
            - type: string
            - type: 'null'
          description: Website returned by the Sendora API.
          title: Website
      required:
        - id
        - status
        - created_at
      title: LeadOut
      type: object
    LeadStatus:
      enum:
        - active
        - unsubscribed
        - dnc
        - bounced
      title: LeadStatus
      type: string
    TrafficLightStatus:
      enum:
        - GREEN
        - YELLOW
        - RED
      title: TrafficLightStatus
      type: string
    ValidationError:
      properties:
        loc:
          description: Loc returned by the Sendora API.
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          description: Msg returned by the Sendora API.
          title: Message
          type: string
        type:
          description: Type returned by the Sendora API.
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Customer API key created in the Sendora dashboard.
      in: header
      name: X-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.