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

# List the members of a contact list

> Returns the subscribed memberships of the list, each carrying its contact with the contact email addresses preloaded. Unsubscribed memberships are not included. The optional `search` term matches the contact first, last and display name. Requires the `contacts:read` scope.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/user/contact-lists/{id}/contacts
openapi: 3.0.0
info:
  title: Brudcast API
  version: 1.0.0
servers:
  - url: https://core-service.prod.brudcast.com
    description: Production
security: []
tags:
  - name: Analytics
    x-displayName: Analytics
  - name: Campaigns
    x-displayName: Campaigns
  - name: Contacts
    x-displayName: Contacts
  - name: Mailboxes
    x-displayName: Mailboxes
  - name: Messages
    x-displayName: Messages
  - name: Sender Identities
    x-displayName: Sender Identities
  - name: Sending Domains
    x-displayName: Sending Domains
  - name: Templates
    x-displayName: Templates
  - name: Webhooks
    x-displayName: Webhooks
paths:
  /api/v1/user/contact-lists/{id}/contacts:
    get:
      tags:
        - Contacts
      summary: List the members of a contact list
      description: >-
        Returns the subscribed memberships of the list, each carrying its
        contact with the contact email addresses preloaded. Unsubscribed
        memberships are not included. The optional `search` term matches the
        contact first, last and display name. Requires the `contacts:read`
        scope.
      parameters:
        - in: header
          name: X-Organization-Id
          required: false
          description: >-
            Required when authenticating with an access token. Optional with an
            API key, whose own organization binding is authoritative; a value
            contradicting it is refused with 403.
          schema:
            type: string
            format: uuid
        - in: query
          name: page
          required: false
          schema:
            type: number
            minimum: 1
        - in: query
          name: limit
          required: false
          schema:
            type: number
            minimum: 1
            maximum: 100
        - in: query
          name: search
          required: false
          schema:
            type: string
            minLength: 1
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactListMembershipObject'
                  meta:
                    type: object
                    properties:
                      total:
                        type: number
                        example: 137
                      perPage:
                        type: number
                        example: 20
                      currentPage:
                        type: number
                        example: 1
                      lastPage:
                        type: number
                        example: 7
                      firstPage:
                        type: number
                        example: 1
                      firstPageUrl:
                        type: string
                        example: /?page=1
                      lastPageUrl:
                        type: string
                        example: /?page=7
                      nextPageUrl:
                        type: string
                        nullable: true
                        example: /?page=2
                      previousPageUrl:
                        type: string
                        nullable: true
                        example: null
                    required:
                      - total
                      - perPage
                      - currentPage
                      - lastPage
                      - firstPage
                      - firstPageUrl
                      - lastPageUrl
                      - nextPageUrl
                      - previousPageUrl
                required:
                  - success
                  - message
                  - data
                  - meta
        '401':
          description: The credential is missing, malformed, revoked or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            The key lacks the scope the endpoint requires, or the organization
            does not match the credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No such contact list in the organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: The payload or query string failed validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: >-
            Rate limit exceeded; retry after the number of seconds in
            `retryAfter`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
      security:
        - apiKey: []
        - apiKeyBearer: []
components:
  schemas:
    ContactListMembershipObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        contactId:
          type: string
          format: uuid
        contactListId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - subscribed
            - unsubscribed
        subscribedAt:
          type: string
          format: date-time
          nullable: true
        unsubscribedAt:
          type: string
          format: date-time
          nullable: true
        unsubscribeReason:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        contact:
          $ref: '#/components/schemas/ContactSummary'
        contactList:
          $ref: '#/components/schemas/ContactListSummary'
      required:
        - id
        - contactId
        - contactListId
        - status
        - subscribedAt
        - unsubscribedAt
        - unsubscribeReason
        - createdAt
        - updatedAt
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Resource not found
        code:
          type: string
          enum:
            - E_VALIDATION_ERROR
            - E_UNAUTHORIZED_ACCESS
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_INSUFFICIENT_SCOPE
            - E_ROW_NOT_FOUND
            - E_TOO_MANY_REQUESTS
            - E_BUSINESS_RULE_VIOLATION
            - E_CAMPAIGN_NOT_SENDABLE
            - INSUFFICIENT_CREDITS
            - SUBSCRIPTION_REQUIRED
          example: E_ROW_NOT_FOUND
      required:
        - success
        - message
        - code
    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: The payload is invalid
        code:
          type: string
          enum:
            - E_VALIDATION_ERROR
            - E_UNAUTHORIZED_ACCESS
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_INSUFFICIENT_SCOPE
            - E_ROW_NOT_FOUND
            - E_TOO_MANY_REQUESTS
            - E_BUSINESS_RULE_VIOLATION
            - E_CAMPAIGN_NOT_SENDABLE
            - INSUFFICIENT_CREDITS
            - SUBSCRIPTION_REQUIRED
          example: E_VALIDATION_ERROR
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
      required:
        - success
        - message
        - code
        - errors
    RateLimitErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Too many requests
        code:
          type: string
          enum:
            - E_VALIDATION_ERROR
            - E_UNAUTHORIZED_ACCESS
            - E_UNAUTHORIZED
            - E_FORBIDDEN
            - E_INSUFFICIENT_SCOPE
            - E_ROW_NOT_FOUND
            - E_TOO_MANY_REQUESTS
            - E_BUSINESS_RULE_VIOLATION
            - E_CAMPAIGN_NOT_SENDABLE
            - INSUFFICIENT_CREDITS
            - SUBSCRIPTION_REQUIRED
          example: E_TOO_MANY_REQUESTS
        retryAfter:
          type: number
          example: 60
      required:
        - success
        - message
        - code
        - retryAfter
    ContactSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        displayName:
          type: string
          nullable: true
          description: >-
            Derived on create from the first and last name, then the first email
            address, falling back to "Unnamed Contact"
        status:
          type: string
          enum:
            - active
            - inactive
            - archived
          nullable: true
        tags:
          type: array
          items:
            type: string
          description: >-
            Tag names, kept for compatibility with the tag records. Empty when
            the query did not load the tags
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        emails:
          type: array
          items:
            $ref: '#/components/schemas/ContactEmailObject'
      required:
        - id
        - organizationId
        - firstName
        - lastName
        - displayName
        - status
        - tags
        - createdAt
        - updatedAt
    ContactListSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
        cuid:
          type: string
          description: Stable public identifier for the list
        organizationId:
          type: string
          format: uuid
        name:
          type: string
          example: Product announcements
        description:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - active
            - inactive
            - archived
        preferredChannels:
          type: array
          items:
            type: string
            enum:
              - email
              - sms
              - imessage
              - telegram
              - push
              - whatsapp
          description: Channels a campaign should prefer when sending to this list
        tags:
          type: array
          items:
            type: string
          description: >-
            Tag names, kept for compatibility with the tag records. Empty when
            the query did not load the tags
        isDefault:
          type: boolean
          description: Whether this is the organization's default list
        subscriberCount:
          type: number
          description: >-
            Subscribed memberships, maintained incrementally as contacts join
            and leave
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - cuid
        - organizationId
        - name
        - description
        - status
        - preferredChannels
        - tags
        - isDefault
        - subscriberCount
        - createdAt
        - updatedAt
    ValidationErrorItem:
      type: object
      properties:
        field:
          type: string
          example: emailAddress
        rule:
          type: string
          example: email
        message:
          type: string
          example: The emailAddress field must be a valid email address
      required:
        - field
        - rule
        - message
    ContactEmailObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        contactId:
          type: string
          format: uuid
        organizationId:
          type: string
          format: uuid
        email:
          type: string
          format: email
          description: Stored encrypted at rest and returned in the clear
        status:
          type: string
          enum:
            - verified
            - unverified
            - bounced
            - complained
            - suppressed
        isPrimary:
          type: boolean
          description: >-
            Setting this does not demote the contact's other records on the same
            channel, so more than one can be primary at once
        bounceCount:
          type: number
        complaintCount:
          type: number
        verifiedAt:
          type: string
          format: date-time
          nullable: true
        lastBouncedAt:
          type: string
          format: date-time
          nullable: true
        lastComplainedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - contactId
        - organizationId
        - email
        - status
        - isPrimary
        - bounceCount
        - complaintCount
        - verifiedAt
        - lastBouncedAt
        - lastComplainedAt
        - createdAt
        - updatedAt
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        An organization API key, prefixed `bk_live_`. Takes precedence over
        `Authorization` when both are sent. The key is bound to one
        organization, and the scopes it was issued with are enforced per
        endpoint.
    apiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: bk_live_...
      description: >-
        The same organization API key sent as `Authorization: Bearer
        bk_live_...`. Accepted only when the value begins with `bk_` and no
        `X-API-Key` header is present.

````