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

# List Contacts

> Retrieves a paginated list of contacts inside the workspace with support for full-text search and complex filters (tags, custom fields, subscription, segments, date ranges, etc.).

Use this endpoint to retrieve a paginated list of contacts in your workspace.

All query parameters are optional. By default, the API returns the first 10 contacts.

You can use the `q` parameter for a full-text search across names, emails, and phone numbers. You can also use advanced filtering by combining tags, custom fields, segments, and date ranges.


## OpenAPI

````yaml GET /api/contacts/me
openapi: 3.1.0
info:
  title: Automate Chats API
  description: >-
    API for managing WhatsApp template messages, contacts, custom fields, tags,
    and external integrations.
  version: 1.0.0
servers:
  - url: https://api.automatechats.com
security:
  - apiKeyAuth: []
paths:
  /api/contacts/me:
    get:
      summary: List Contacts
      description: >-
        Retrieves a paginated list of contacts inside the workspace with support
        for full-text search and complex filters (tags, custom fields,
        subscription, segments, date ranges, etc.).
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: 'Number of items per page (max: 100)'
          required: false
          schema:
            type: integer
            default: 10
        - name: q
          in: query
          description: >-
            Free-text search query matching first name, last name, phone number,
            or email.
          required: false
          schema:
            type: string
        - name: subscribed
          in: query
          description: Filter by WhatsApp subscription status.
          required: false
          schema:
            type: boolean
        - name: tagsId
          in: query
          description: >-
            Filter by tags using comma-separated Tag IDs (e.g. `id1,id2`). Use
            in combination with `tagsMode`.
          required: false
          schema:
            type: string
        - name: segmentId
          in: query
          description: Filter by segment ID(s). Comma-separated list supported.
          required: false
          schema:
            type: string
        - name: startDate
          in: query
          description: Filter contacts created on or after this ISO date-time.
          required: false
          schema:
            type: string
            format: date-time
        - name: endDate
          in: query
          description: Filter contacts created on or before this ISO date-time.
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Contacts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Contacts fetched successfully
                  data:
                    type: object
                    properties:
                      contacts:
                        type: array
                        items:
                          $ref: '#/components/schemas/Contact'
                      pagination:
                        type: object
                        properties:
                          page:
                            type: integer
                            example: 1
                          limit:
                            type: integer
                            example: 10
                          total:
                            type: integer
                            example: 145
                          totalPages:
                            type: integer
                            example: 15
                  timestamp:
                    type: string
                    format: date-time
                    example: '2026-05-18T15:00:00.000Z'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
components:
  schemas:
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Unique MongoDB ID of the contact
          example: 65e0bc51c12e4d70834b070e
        firstName:
          type: string
          description: Contact's first name
          example: John
        lastName:
          type: string
          description: Contact's last name
          example: Doe
        chatName:
          type: string
          description: Formatted name used in active chats
          example: John Doe
        email:
          type: string
          format: email
          description: Contact's email address
          example: john.doe@example.com
        phoneNumber:
          type: string
          description: Contact's phone number without country code
          example: '9876543210'
        countryCode:
          type: string
          description: Contact's telephone country code
          example: '+91'
        source:
          type: string
          description: >-
            How the contact was entered into the system (e.g. `manual`,
            `import`, `widget`, `whatsapp`)
          example: manual
        subscribed:
          type: boolean
          description: WhatsApp subscription status
          example: true
        tagsId:
          type: array
          description: List of tag IDs assigned to this contact
          items:
            type: string
          example:
            - 65e0bc51c12e4d70834b070e
        tags:
          type: array
          description: Detailed metadata of tags assigned to this contact
          items:
            $ref: '#/components/schemas/ContactTag'
        customFields:
          type: array
          description: Detailed custom field values assigned to this contact
          items:
            type: object
            properties:
              id:
                type: string
                description: Custom field identifier
                example: 65f12ab3c9e4f1a2b3c4d5e6
              label:
                type: string
                description: Friendly name of the custom field
                example: Company Name
              value:
                description: Value associated with this custom field for this contact
                example: Google Deepmind
        dob:
          type: string
          format: date
          description: Date of Birth (ISO 8601 YYYY-MM-DD)
          example: '1990-01-15'
        anniversary:
          type: string
          format: date
          description: Anniversary date (ISO 8601 YYYY-MM-DD)
          example: '2020-06-20'
        workspaceId:
          type: integer
          description: Multi-tenant workspace ID ownership
          example: 246
        createdBy:
          type: string
          description: ID of the user who created this contact
          example: 6996aeeedf12574080a99d81
        createdAt:
          type: string
          format: date-time
          description: Timestamp when contact was created
          example: '2026-05-18T15:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when contact was last updated
          example: '2026-05-18T15:05:00.000Z'
    ContactTag:
      type: object
      properties:
        tagId:
          type: string
          description: Unique ID of the tag
          example: 65e0bc51c12e4d70834b070e
        name:
          type: string
          description: Friendly tag name
          example: VIP
        text_color:
          type: string
          description: Hex text color code
          example: '#ffffff'
        background_color:
          type: string
          description: Hex background color code
          example: '#ef4444'
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        code:
          type: integer
          example: 400
        message:
          type: string
          example: 'Invalid input: field first_name is required.'
        error:
          description: Optional validation error details or raw stack traces.
        timestamp:
          type: string
          format: date-time
          example: '2026-05-18T15:00:00.000Z'
  responses:
    UnauthorizedError:
      description: Unauthorized (missing or invalid API key / JWT token)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: error
            code: 401
            message: >-
              Unauthorized access: Invalid or missing authentication
              credentials.
            timestamp: '2026-05-18T15:00:00.000Z'
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````