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

# List leads

> Incrementally list leads. Requires `updatedSince` and/or `createdSince`. Soft-deleted leads are included (`deleted: true`); treat as removals. Use `lastActivityAt` to decide whether to fetch events.



## OpenAPI

````yaml get /leads
openapi: 3.0.1
info:
  title: AttentPublicAPI
  version: '2024-05-17T21:09:13Z'
servers:
  - url: https://api.attent.app/v1
security: []
paths:
  /leads:
    get:
      tags:
        - Leads
      description: >-
        Incrementally list leads. Requires `updatedSince` and/or `createdSince`.
        Soft-deleted leads are included (`deleted: true`); treat as removals.
        Use `lastActivityAt` to decide whether to fetch events.
      operationId: listLeads
      parameters:
        - name: updatedSince
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            ISO 8601 timestamp. Returns leads whose `updatedAt` is greater than
            or equal to this value.
        - name: createdSince
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: >-
            ISO 8601 timestamp. Returns leads whose `createdAt` is greater than
            or equal to this value.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
          description: >-
            Maximum number of leads to return per page. Defaults to 100, max
            1000.
        - name: nextToken
          in: query
          required: false
          schema:
            type: string
          description: >-
            Opaque cursor returned by a prior response. Pass it back to fetch
            the next page.
      responses:
        '200':
          description: A page of leads ordered by the chosen timestamp ascending.
          content:
            application/json:
              schema:
                type: object
                properties:
                  leads:
                    type: array
                    items:
                      $ref: '#/components/schemas/incrementalLead'
                  nextToken:
                    type: string
                    nullable: true
                    description: >-
                      Cursor for the next page. `null` if there are no more
                      results.
              example:
                leads:
                  - id: room_abc
                    firstName: John
                    lastName: Doe
                    phone: '+15555555555'
                    email: john.doe@example.com
                    customerProfile: My Customer Profile
                    createdAt: '2026-05-01T12:00:00.000Z'
                    updatedAt: '2026-05-14T15:30:00.000Z'
                    lastActivityAt: '2026-05-14T15:30:00.000Z'
                    additionalInfo:
                      key1: value1
                    hasReplied: true
                    isHot: true
                    isQualified: false
                    isUnsubscribed: false
                    isAiOn: true
                    tags:
                      - id: tag1
                        name: Tag 1
                        condition: Condition 1
                    summary: Summary of the conversation.
                    externalLeadId: 00Q5g00000ABCDEAA1
                    deleted: false
                    deletedAt: null
                nextToken: >-
                  eyJzZWFyY2hBZnRlciI6WyIyMDI2LTA1LTE0VDE1OjMwOjAwLjAwMFoiLCJyb29tX2FiYyJdfQ==
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      security:
        - api_key: []
components:
  schemas:
    incrementalLead:
      type: object
      description: >-
        A lead record returned from the incremental list endpoint. Includes
        lifecycle fields (`updatedAt`, `deleted`, `deletedAt`) needed for
        data-warehouse sync.
      properties:
        id:
          type: string
          description: Stable unique identifier for the lead.
        firstName:
          type: string
          description: >-
            The first name of the lead. May be null on soft-deleted leads after
            PII scrub.
          nullable: true
        lastName:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        customerProfile:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          description: >-
            Bumped whenever ANY field on this lead changes — profile edits, tag
            changes, or a new/updated/deleted event. Use as the cursor for `GET
            /leads?updatedSince=T`.
        lastActivityAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Bumped only when an interaction event on this lead changes — a new
            event, an edit (e.g. message delivery status), or a soft-delete. Use
            to skip `GET /leads/{leadId}/events` for leads whose `updatedAt`
            bumped only due to profile/tag changes.
        additionalInfo:
          type: object
          nullable: true
        hasReplied:
          type: boolean
        isHot:
          type: boolean
        isQualified:
          type: boolean
        isUnsubscribed:
          type: boolean
        isUnsubscribedEmail:
          type: boolean
        isAiOn:
          type: boolean
        summary:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              condition:
                type: string
        externalLeadId:
          type: string
          nullable: true
        deleted:
          type: boolean
          description: >-
            True if the lead has been deleted. Treat as a removal in your sync
            target.
        deletedAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp of when the lead was deleted, or null if not
            deleted.
      required:
        - id
        - deleted
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            example:
              message: 'Invalid format for field: phone'
    '401':
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            example:
              message: Unauthorized
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
            example:
              message: Internal Server Error
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````