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

# Get All Merchants ( STABLE )

> This endpoint provides a comprehensive list of all registered merchants, including essential details. Pagination options are available to efficiently manage large datasets.



## OpenAPI

````yaml https://api.grailpay.com/docs?api-docs.json get /api/v3/merchants
openapi: 3.0.0
info:
  title: GrailPay ACH API
  description: API Documentation for moving funds via ACH using the GrailPay ACH API
  version: 2025.12.19.2
servers:
  - url: https://api.grailpay.com
    description: Production environment
  - url: https://api-sandbox.grailpay.com
    description: Sandbox environment
security: []
tags:
  - name: Users
    description: >-
      API Endpoints used for the onboarding and managing People, Businesses, and
      Merchants.
  - name: Transactions
    description: API Endpoints used for creating and managing transactions.
  - name: Payouts
    description: API Endpoints used for fetching payout information.
  - name: Refunds
    description: API Endpoints used for creating and retrieving refunds.
  - name: Bank Accounts
    description: API Endpoints used for adding and managing bank accounts.
  - name: Webhooks
    description: API Endpoints used for registering and de-registering webhooks.
  - name: Billing
    description: API Endpoints used for retrieving billing information.
  - name: Stable
    description: Stable, up-to-date APIs that are recommended for current integration.
  - name: Sunsetting
    description: Sunsetting APIs that are still supported but scheduled for deprecation.
  - name: Deprecated
    description: Deprecated APIs that are no longer supported and should be removed.
  - name: SUNSETTING
    description: SUNSETTING
paths:
  /api/v3/merchants:
    get:
      tags:
        - Users
        - Stable
      summary: Get All Merchants ( STABLE )
      description: >-
        This endpoint provides a comprehensive list of all registered merchants,
        including essential details. Pagination options are available to
        efficiently manage large datasets.
      operationId: e7ddae992283223ff98ce4cdea429ce6
      parameters:
        - name: filter[uuid]
          in: query
          description: Filter by merchant UUID
          required: false
          schema:
            type: string
            format: uuid
            example: 7c41f6a2-a4b9-4df8-9225-2c1b7312042e
        - name: filter[name]
          in: query
          description: Filter by merchant name
          required: false
          schema:
            type: string
            example: John Inc
        - name: filter[tin]
          in: query
          description: Filter by EIN (TIN) number
          required: false
          schema:
            type: string
            example: '123456789'
        - name: sort
          in: query
          description: >-
            Sort by field (created_at, name). Prefix with '-' for descending
            order
          required: false
          schema:
            type: string
            example: '-created_at'
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            example: 1
        - name: per_page
          in: query
          description: Number of records per page
          required: false
          schema:
            type: integer
            default: 15
            example: 15
      responses:
        '200':
          description: The response returned from a successful call to listing merchants.
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: ''
                  data:
                    properties:
                      merchants:
                        type: array
                        items:
                          properties:
                            merchant:
                              $ref: '#/components/schemas/V3MerchantResponseObject'
                            beneficial_owners:
                              type: array
                              items:
                                $ref: >-
                                  #/components/schemas/V3BeneficialOwnerResponseObject
                            bank_accounts:
                              type: array
                              items:
                                $ref: '#/components/schemas/V3BankAccountResponse'
                            relations:
                              $ref: >-
                                #/components/schemas/V3PersonRelationResponseObject
                          type: object
                    type: object
                  errors:
                    type: object
                    example: null
                    nullable: true
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                  meta:
                    $ref: '#/components/schemas/V3ListingPaginationResponse'
                type: object
        '400':
          description: 400 - Bad Request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/V3ErrorInvalidParameters400'
                  - $ref: '#/components/schemas/V3ErrorInvalidAcceptHeader400'
        '401':
          description: 401 - Unauthorized
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/V3ErrorInvalidToken401'
                  - $ref: '#/components/schemas/V3ErrorUnauthorized401'
        '422':
          description: 422 - Unprocessable Entity
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: The given data was invalid.
                  data:
                    type: object
                    example: null
                    nullable: true
                  errors:
                    properties:
                      filter.uuid:
                        type: object
                        example:
                          - The merchant UUID must be a valid UUID.
                      filter.name:
                        type: object
                        example:
                          - The merchant name must be a string.
                          - >-
                            The merchant name may not be greater than 255
                            characters.
                      filter.tin:
                        type: object
                        example:
                          - The EIN (TIN) number name must be a string.
                          - The EIN (TIN) number must consist of 9 digits.
                      sort:
                        type: object
                        example:
                          - >-
                            The sort option must be one of the followings:
                            created_at, -created_at, name, -name
                      per_page:
                        type: object
                        example:
                          - The per page may not be greater than 200.
                          - The per page must be at least 1.
                          - The per page must be an integer.
                      page:
                        type: object
                        example:
                          - The page must be an integer.
                          - The page must be at least 1.
                    type: object
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                properties:
                  status:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Something went wrong on our side. Please contact support.
                  data:
                    type: object
                    example: null
                    nullable: true
                  errors:
                    type: object
                    example: null
                    nullable: true
                  request_id:
                    type: string
                    format: uuid
                    example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
                type: object
      security:
        - ApiToken: []
components:
  schemas:
    V3MerchantResponseObject:
      properties:
        uuid:
          type: string
          example: c6bcfbbb-98ff-4d8b-a8f5-1559c3dcb718
        business_type:
          type: string
          example: merchant
        kyb_status:
          type: string
          example: IN_REVIEW
        kyb_rejected_reason:
          type: string
          example: null
        name:
          type: string
          example: Acme Inc.
        tin:
          type: string
          example: '123456789'
        trading_name:
          type: string
          example: Acme Corp
        entity_type:
          type: string
          example: Sole Trader
        incorporation_date:
          type: string
          example: '2024-02-02'
        incorporation_state:
          type: string
          example: CO
        address_type:
          type: string
          example: Registered
        address:
          $ref: '#/components/schemas/V3AddressObject'
        transaction_fee_percent:
          type: number
          format: float
          example: 2.5
        transaction_fee_fixed:
          type: number
          example: 100
        maximum_transaction_fee:
          type: number
          example: 5000
        payout_type:
          type: string
          example: batch
        client_reference_id:
          type: string
          example: reference_12345
        timestamps:
          $ref: '#/components/schemas/V3TimestampsObject'
      type: object
    V3BeneficialOwnerResponseObject:
      properties:
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        dob:
          type: string
          example: '2023-04-11'
        ssn9:
          type: string
          example: '123456789'
        address:
          $ref: '#/components/schemas/V3AddressObject'
        is_beneficial_owner:
          type: boolean
          example: true
        is_director:
          type: boolean
          example: false
        is_significant_control_person:
          type: boolean
          example: false
        ownership_percentage:
          type: number
          format: float
          example: 25
        email:
          type: string
          example: owner@test.com
        phone:
          type: string
          example: '2457856490'
        occupation:
          type: string
          example: Co-founder
        timestamps:
          $ref: '#/components/schemas/V3TimestampsObject'
      type: object
    V3BankAccountResponse:
      properties:
        aggregator_type:
          type: string
          example: manual
        uuid:
          type: string
          format: uuid
          example: 9b97f121-a449-4b52-9f36-6c55f18394d6
        is_default:
          type: boolean
          example: true
        account_number:
          type: string
          example: '********1234'
        routing_number:
          type: string
          example: '*****6789'
        account_name:
          type: string
          example: John Doe
        account_type:
          type: string
          example: checking
        timestamps:
          $ref: '#/components/schemas/V3TimestampsObject'
      type: object
    V3PersonRelationResponseObject:
      properties:
        person:
          properties:
            uuid:
              type: string
              example: 7c41f6a2-a4b9-4df8-9225-2c1b7312042e
          type: object
      type: object
    V3ListingPaginationResponse:
      properties:
        current_page:
          type: number
          example: 1
        from:
          type: number
          example: 1
        last_page:
          type: number
          example: 25
        links:
          type: array
          items:
            type: object
        per_page:
          type: number
          example: 15
        to:
          type: number
          example: 15
        total:
          type: number
          example: 370
      type: object
    V3ErrorInvalidParameters400:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid Parameters Received
        data:
          type: string
          example: null
          nullable: true
        errors:
          type: string
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorInvalidAcceptHeader400:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid value provided for Accept header.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorInvalidToken401:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid token.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3ErrorUnauthorized401:
      properties:
        status:
          type: boolean
          example: false
        message:
          type: string
          example: This action is unauthorized.
        data:
          type: object
          example: null
          nullable: true
        errors:
          type: object
          example: null
          nullable: true
        request_id:
          type: string
          format: uuid
          example: 2d6a4c39-8fcf-4d80-9189-b4764eac31f2
      type: object
    V3AddressObject:
      properties:
        line_1:
          type: string
          example: 10554 W Quarles Ave
        line_2:
          type: string
          example: Suite 123
          nullable: true
        city:
          type: string
          example: Littleton
        state:
          type: string
          example: CO
        zip:
          type: string
          example: '80127'
      type: object
    V3TimestampsObject:
      properties:
        created_at:
          type: string
          example: '2024-06-25 13:57:03'
      type: object
  securitySchemes:
    ApiToken:
      type: http
      description: >-
        Token-based authentication using Authorization: Bearer <YOUR_API_KEY>
        provided by the GrailPay Support Team.
      bearerFormat: Token
      scheme: bearer

````