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

# List the users enrolled in a program

> Returns the users that have an enrollment on the program identified by the `X-Meridian-Program-Id` header, newest first. A user created through `POST /v1/auth/users` appears here once enrollment has started. Both SINGLE_USER and MULTI_USER integrations may call this endpoint; no `X-Meridian-User-Id` header is required.



## OpenAPI

````yaml /products/meridian-accounts/api-reference/meridian-accounts.json get /v1/users
openapi: 3.1.1
info:
  title: Meridian API
  version: '1.0'
  description: API documentation for Meridian services
  contact:
    name: Meridian
    url: https://mnai.com
    email: support@mnai.com
  license:
    name: Proprietary
    url: https://mnai.com
servers:
  - url: https://sandbox-api.va.meridianpay.com
    description: Sandbox
  - url: https://api.va.mnai.com
    description: Production
security: []
paths:
  /v1/users:
    get:
      tags:
        - Users
      summary: List the users enrolled in a program
      description: >-
        Returns the users that have an enrollment on the program identified by
        the `X-Meridian-Program-Id` header, newest first. A user created through
        `POST /v1/auth/users` appears here once enrollment has started. Both
        SINGLE_USER and MULTI_USER integrations may call this endpoint; no
        `X-Meridian-User-Id` header is required.
      operationId: listMeridianAccountsUsers
      parameters:
        - name: X-Meridian-Api-Key
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Partner API key issued by
            Meridian during provisioning.
          required: true
          schema:
            type: string
          example: your-api-key
        - name: X-Meridian-Timestamp
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Current time in milliseconds
            since the Unix epoch. Must be within 60 seconds of the request.
          required: true
          schema:
            type: string
          example: '1749566400000'
        - name: X-Meridian-Program-Id
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Identifies the program
            context for the request.
          required: true
          schema:
            type: string
          example: your-program-id
        - name: X-Meridian-User-Id
          in: header
          description: >-
            Server-to-server (HMAC) requests only. Identifies the Meridian user
            targeted by the request. Required for MULTI_USER integrations; omit
            for SINGLE_USER.
          schema:
            type: string
          example: user_123
        - name: pageIndex
          in: query
          description: Zero-based page index. Defaults to 0.
          schema:
            type: string
        - name: pageSize
          in: query
          description: Number of users per page, between 1 and 25. Defaults to 25.
          schema:
            type: string
      responses:
        '200':
          description: The users enrolled in the requested program
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersResponse'
              examples:
                multi_user_program:
                  $ref: '#/components/examples/ListUsersMultiUserProgram'
                single_user_program:
                  $ref: '#/components/examples/ListUsersSingleUserProgram'
        '400':
          description: The program header is missing, or a paging parameter is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '403':
          description: API key is not entitled for the requested program
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '404':
          description: Program was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
        '500':
          description: Unexpected error while listing the users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeridianError'
      security:
        - partner-api-key: []
components:
  schemas:
    UsersResponse:
      type: object
      title: Users Response
      description: Users enrolled in the requested program
      required:
        - data
        - pageIndex
        - pageSize
        - totalRecords
      properties:
        data:
          type: array
          description: List of users enrolled in the program
          items:
            $ref: '#/components/schemas/UserDetails'
        pageIndex:
          type: integer
          description: Current page index
          example: 0
        pageSize:
          type: integer
          description: Number of records per page
          example: 25
        totalRecords:
          type: integer
          description: Total number of enrolled users on the program
          example: 3
    MeridianError:
      type: object
      title: MeridianError
      description: >-
        Represents an error response from the Meridian API, including validation
        errors and an optional error code.
      required:
        - message
      properties:
        validationErrors:
          type: array
          description: >-
            An array of validation errors that occurred during the processing of
            the request. This field is optional and may be empty if there are no
            validation errors.
          items:
            $ref: '#/components/schemas/ValidationError'
        errorCode:
          type: string
          description: >-
            Machine-readable code identifying the failure. Absent when the
            failure is fully described by `validationErrors`. Clients should
            tolerate codes added in the future.
          enum:
            - UNAUTHORIZED
            - FORBIDDEN
            - NOT_FOUND
            - INVALID_REQUEST
            - INTERNAL_ERROR
            - INFORMATION_REQUEST_NOT_EDITABLE
            - INVALID_USER_TYPE
            - SINGLE_USER_KEY_NOT_ALLOWED
            - USER_ID_HEADER_REQUIRED
            - USER_ID_HEADER_NOT_ALLOWED
            - PDF_PAGE_LIMIT_EXCEEDED
            - PDF_PASSWORD_PROTECTED
            - PDF_UNREADABLE
        message:
          type: string
          description: >-
            A human-readable message describing the error. This field is
            required and should provide a clear explanation of the error that
            occurred.
    UserDetails:
      type: object
      title: User Details
      description: A Meridian user enrolled in the program
      required:
        - userId
        - type
        - enrollmentStatus
        - createdAt
        - updatedAt
      properties:
        userId:
          type: string
          description: Meridian user identifier, usable as the 'X-Meridian-User-Id' header
          example: ususr-h2vuw0jaswgpzyxluhpz2709
        externalId:
          type:
            - string
            - 'null'
          description: Partner-defined external identifier for the user, when one is linked
          example: partner-user-123
        type:
          type: string
          description: Type of Meridian user
          example: PERSON
          enum:
            - PERSON
            - BUSINESS
        name:
          type:
            - string
            - 'null'
          description: >-
            Display name: the person's full name, or the business legal name for
            a business user
          example: Jane Doe
        email:
          type:
            - string
            - 'null'
          description: Contact email address, when one is on record for the user
          example: jane.doe@example.com
        enrollmentStatus:
          type: string
          description: Current status of the user's enrollment on this program
          example: ACTIVE
          enum:
            - INACTIVE
            - ACTIVE
        enrollmentStatusReason:
          type:
            - string
            - 'null'
          description: Reason for the current enrollment status, when one applies
          example: ACTIVATION_REJECTED
          enum:
            - REVOKED
            - ACTIVATION_REJECTED
            - null
        createdAt:
          type: string
          description: Timestamp when the user was created
          example: '2026-06-09T14:30:00Z'
          format: date-time
        updatedAt:
          type: string
          description: Timestamp when the user was last updated
          example: '2026-06-09T15:20:00Z'
          format: date-time
    ValidationError:
      type: object
      title: ValidationError
      description: >-
        Represents a validation error that occurred during the processing of a
        request to the Meridian API. One of the following types of validation
        errors may be present: InvalidFormat, InvalidValue, MissingValue,
        UnprocessableValue, UnexpectedVerificationError, MissingRequestBody,
        MissingPathParameter, MissingQueryParameter, or NotFound. Each
        validation error includes a reference to the field that caused the error
        and a message describing the error.
      required:
        - type
      properties:
        type:
          type: string
          description: Identifies which ValidationError this is.
          enum:
            - InvalidFormat
            - InvalidValue
            - MissingPathParameter
            - MissingQueryParameter
            - MissingRequestBody
            - MissingValue
            - NotFound
            - UnexpectedVerificationError
            - Unknown
            - UnprocessableValue
      discriminator:
        propertyName: type
        mapping:
          InvalidFormat:
            $ref: '#/components/schemas/InvalidFormat'
          InvalidValue:
            $ref: '#/components/schemas/InvalidValue'
          MissingPathParameter:
            $ref: '#/components/schemas/MissingPathParameter'
          MissingQueryParameter:
            $ref: '#/components/schemas/MissingQueryParameter'
          MissingRequestBody:
            $ref: '#/components/schemas/MissingRequestBody'
          MissingValue:
            $ref: '#/components/schemas/MissingValue'
          NotFound:
            $ref: '#/components/schemas/NotFound'
          UnexpectedVerificationError:
            $ref: '#/components/schemas/UnexpectedVerificationError'
          Unknown:
            $ref: '#/components/schemas/Unknown'
          UnprocessableValue:
            $ref: '#/components/schemas/UnprocessableValue'
    InvalidFormat:
      title: InvalidFormat
      description: The provided value exists, but its format is invalid for the field.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    InvalidValue:
      title: InvalidValue
      description: >-
        The provided value is syntactically valid, but not accepted for the
        field.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    MissingPathParameter:
      title: MissingPathParameter
      description: A required path parameter was not supplied.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    MissingQueryParameter:
      title: MissingQueryParameter
      description: A required query parameter was not supplied.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    MissingRequestBody:
      title: MissingRequestBody
      description: >-
        The request body is missing or does not contain the required non-null
        fields.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          properties:
            message:
              type: string
              description: A human-readable explanation of the validation failure.
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
    MissingValue:
      title: MissingValue
      description: A required value for the field was not provided.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    NotFound:
      title: NotFound
      description: The referenced principal object was not found.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    UnexpectedVerificationError:
      title: UnexpectedVerificationError
      description: A downstream verification step failed while checking the value.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
    Unknown:
      title: Unknown
      description: >-
        A validation error occurred but the specific field could not be
        determined.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          properties:
            message:
              type: string
              description: A human-readable explanation of the validation failure.
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
    UnprocessableValue:
      title: UnprocessableValue
      description: The provided value cannot be processed into a valid result.
      allOf:
        - $ref: '#/components/schemas/ValidationError'
        - type: object
          required:
            - fieldRef
          properties:
            fieldRef:
              type: string
              description: The field or parameter that triggered the validation error.
            message:
              type: string
              description: A human-readable explanation of the validation failure.
  examples:
    ListUsersMultiUserProgram:
      value:
        data:
          - userId: ususr-h2vuw0jaswgpzyxluhpz2709
            externalId: partner-user-123
            type: PERSON
            name: Jane Doe
            email: jane.doe@example.com
            enrollmentStatus: ACTIVE
            createdAt: '2026-06-09T14:30:00Z'
            updatedAt: '2026-06-09T15:20:00Z'
          - userId: ususr-coxxvofk5km4tz1r28c7gcfk
            externalId: partner-user-124
            type: PERSON
            name: John Smith
            email: john.smith@example.com
            enrollmentStatus: INACTIVE
            enrollmentStatusReason: ACTIVATION_REJECTED
            createdAt: '2026-06-08T09:05:00Z'
            updatedAt: '2026-06-08T11:42:00Z'
          - userId: ususr-8mzq1lp4xdnr6vtk93wybj0s
            externalId: partner-business-77
            type: BUSINESS
            name: Acme Inc
            enrollmentStatus: ACTIVE
            createdAt: '2026-06-01T10:00:00Z'
            updatedAt: '2026-06-02T08:15:00Z'
        pageIndex: 0
        pageSize: 25
        totalRecords: 3
    ListUsersSingleUserProgram:
      value:
        data:
          - userId: ususr-8mzq1lp4xdnr6vtk93wybj0s
            externalId: partner-business-77
            type: BUSINESS
            name: Acme Inc
            enrollmentStatus: ACTIVE
            createdAt: '2026-06-01T10:00:00Z'
            updatedAt: '2026-06-02T08:15:00Z'
        pageIndex: 0
        pageSize: 25
        totalRecords: 1
  securitySchemes:
    partner-api-key:
      name: X-Meridian-Signature
      in: header
      description: >-
        Meridian HMAC header authentication, for server-to-server calls.


        Required headers:
          - `X-Meridian-Api-Key`
          - `X-Meridian-Timestamp`
          - `X-Meridian-Program-Id`
          - `X-Meridian-User-Id` (MULTI_USER integrations only)
          - `X-Meridian-Signature`

        `X-Meridian-Signature` is the HMAC SHA-256 signature of the canonical
        request string, computed per request. See
        [Authentication](/products/meridian-accounts/guides/authentication-overview)
        for how to construct it.
      type: apiKey

````