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

# List leads

> Filter by `status` to read one pipeline stage. Note that `status` holds a **stage
key**, not a display name — fetch the keys from
[`GET /v1/lead-stages`](/api-reference/pipeline/list-pipeline-stages) rather than
hard-coding `"won"`, which tenants rename.




## OpenAPI

````yaml /openapi/public-api.yaml get /v1/leads
openapi: 3.1.0
info:
  title: Linkiasoft API
  version: 1.0.0
  description: >
    Send and read messages across WhatsApp, Instagram, Messenger and Telegram,
    and read

    and update the CRM behind them — leads, pipeline stages, company contacts
    and activity

    history.


    Every endpoint is authenticated with a tenant-scoped API key and returns
    only data

    belonging to that key's workspace.


    **Two hosts, one key.** Messaging lives on `social.linkiasoft.com` and the
    CRM on

    `api.linkiasoft.com`. Each endpoint below shows its own base URL; the same
    API key

    authenticates against both.
servers:
  - url: https://social.linkiasoft.com/api
    description: Production
security:
  - apiKey: []
    tenantId: []
tags:
  - name: Conversations
    description: Read threads and send messages.
  - name: Templates
    description: Approved WhatsApp message templates.
  - name: Channels
    description: The connected accounts you can send from.
  - name: Leads
    description: Deals moving through your pipeline.
  - name: Pipeline
    description: The stages a lead can sit in.
  - name: Contacts
    description: People attached to a company.
  - name: Activities
    description: Logged calls, emails, meetings and follow-ups.
  - name: Customers
    description: The companies and accounts your contacts belong to.
  - name: Tags
    description: Labels applied to customers, contacts and leads.
  - name: Quick replies
    description: Team-shared canned responses.
  - name: WhatsApp groups
    description: Create and manage WhatsApp group chats.
paths:
  /v1/leads:
    servers:
      - url: https://api.linkiasoft.com/api
    get:
      tags:
        - Leads
      summary: List leads
      description: >
        Filter by `status` to read one pipeline stage. Note that `status` holds
        a **stage

        key**, not a display name — fetch the keys from

        [`GET /v1/lead-stages`](/api-reference/pipeline/list-pipeline-stages)
        rather than

        hard-coding `"won"`, which tenants rename.
      operationId: listLeads
      parameters:
        - name: status
          in: query
          description: Stage key.
          schema:
            type: string
        - name: assigned_to_user_id
          in: query
          schema:
            type: string
            format: uuid
        - name: source
          in: query
          schema:
            type: string
        - name: priority
          in: query
          schema:
            type: string
            enum:
              - urgent
              - high
              - medium
              - low
        - name: search
          in: query
          description: Free text over name, email, and company.
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
        - name: offset
          in: query
          description: >
            Wins over `page` when supplied. Page by rows-already-held when
            reading a board:

            a lead leaving a stage mid-read shifts a page-numbered window and
            skips a row.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: One page of leads.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - total
                  - page
                  - limit
                  - totalPages
                  - hasMore
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lead'
                  total:
                    type: integer
                  page:
                    type: integer
                  limit:
                    type: integer
                  totalPages:
                    type: integer
                  hasMore:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  schemas:
    Lead:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        company_name:
          type: string
        status:
          type: string
          description: The lead's stage **key** — see `GET /v1/lead-stages`.
        customer_type:
          type: string
          enum:
            - individual
            - business
        industry:
          type: string
        source:
          type: string
          description: Where the lead came from, e.g. `whatsapp` or `website`.
        assigned_to_user_id:
          type: string
          format: uuid
        priority:
          type: string
          enum:
            - urgent
            - high
            - medium
            - low
        probability:
          type: integer
          description: Percentage, 0–100.
        value:
          type:
            - number
            - 'null'
          description: Deal size.
        currency:
          type: string
        expected_close_date:
          type:
            - string
            - 'null'
          format: date
        tags:
          type: array
          items:
            type: string
            format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          description: A sentence explaining the failure, or a list of field errors.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        error:
          type: string
      examples:
        - statusCode: 403
          message: 'API key missing required scope(s): conversations:read'
          error: Forbidden
  responses:
    Unauthorized:
      description: The API key is missing, invalid, revoked, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >
        The key is valid but lacks the scope for this endpoint, or the workspace
        has hit a

        plan limit (for example its monthly active-contact quota).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        Your workspace API key. Create one in **Settings → API Keys**; the
        plaintext value

        is shown once and never again.


        Keys are scoped. A key needs `conversations:send` to send,
        `conversations:read` to

        read threads and messages, `templates:read` to list templates, and
        `channels:read`

        to list channels. A key missing the scope for an endpoint gets `403`.


        The CRM endpoints use the same `resource:action` form: `leads:read`,
        `leads:create`,

        `leads:update`, `leads:delete`, `customers:read`, `customers:create`,

        `customers:update`, `customers:delete`, `customers:manage`.


        Several resources have no scope of their own and borrow one:


        | Resource | Governed by |

        |---|---|

        | Contacts | `customers:*` |

        | Activities | `customers:*` for customer activities, `leads:*` for lead
        activities |

        | Tags | `customers:read` to list, `customers:manage` to change |

        | Pipeline stages | `leads:*` |

        | Quick replies | `quick-replies:read` / `quick-replies:write` |

        | WhatsApp groups | `wa-groups:manage` |


        Grant only what the integration needs — a key that only sends
        notifications should

        hold `conversations:send` and nothing else.
    tenantId:
      type: apiKey
      in: header
      name: X-Tenant-Id
      description: >
        Your workspace UUID. Required on every request **in addition to**
        `x-api-key`.


        It does not select the workspace — data access is always scoped to the
        workspace

        that owns the API key, and a mismatched value cannot read anyone else's
        data.

````