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

# List taxpayers

> GET /taxpayers

Returns the taxpayers in the credential's organization, one page at a time.
See the [Transcripts overview](https://docs.taxrock.com/api-reference/transcripts/overview.md).


## OpenAPI

````yaml api-reference/openapi-direct.json GET /taxpayers
openapi: 3.1.0
info:
  title: TaxRock API (direct access)
  version: 1.0.0
  description: >-
    The TaxRock API with direct access: a credential issued for a TaxRock
    organization reads that organization's data. See Getting started.
servers:
  - url: https://api-demo.taxrock.com
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /taxpayers:
    get:
      tags:
        - Taxpayers
      summary: List taxpayers
      description: >-
        Lists the taxpayers in the credential's organization, one page at a
        time.
      operationId: listTaxpayers
      parameters:
        - name: page
          in: query
          required: false
          description: The page number, from 1.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          required: false
          description: Taxpayers per page.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: One page of taxpayers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxpayerPage'
              example:
                taxpayers:
                  - id: 00000000-0000-4000-8000-0000000000a1
                    name: Example Holdings LLC
                    type: Business
                    tin: '000000000'
                  - id: 00000000-0000-4000-8000-0000000000a2
                    name: Taylor Example
                    type: Individual
                    tin: '000000000'
                page: 1
                pageSize: 100
                totalCount: 2
                hasNextPage: false
        '400':
          description: >-
            `page` or `pageSize` is not an integer. `error` is
            `invalid_request`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalidRequest:
                  summary: Malformed value
                  value:
                    error: invalid_request
                    message: The value 'abc' is not valid.
        '401':
          description: Missing or invalid access token. Get a new token.
        '403':
          description: >-
            `error` is `forbidden` when the credential is not set up for direct
            access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                forbidden:
                  summary: Credential not set up for direct access
                  value:
                    error: forbidden
                    message: This client is not authorized for direct access.
components:
  schemas:
    TaxpayerPage:
      type: object
      required:
        - taxpayers
        - page
        - pageSize
        - totalCount
        - hasNextPage
      properties:
        taxpayers:
          type: array
          items:
            $ref: '#/components/schemas/TaxpayerListItem'
          description: The page's taxpayers.
        page:
          type: integer
          description: The page number.
        pageSize:
          type: integer
          description: The page size.
        totalCount:
          type: integer
          description: Taxpayers across all pages.
        hasNextPage:
          type: boolean
          description: Whether another page follows.
    ApiError:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Machine-readable error code, e.g. `invalid_request` or `forbidden`.
        message:
          type: string
          description: Human-readable explanation.
    TaxpayerListItem:
      type: object
      required:
        - id
        - name
        - type
        - tin
      properties:
        id:
          type: string
          format: uuid
          description: The taxpayer's id.
        name:
          type: string
          description: The business name, or an individual's first and last name.
        type:
          $ref: '#/components/schemas/TaxpayerType'
        tin:
          type: string
          description: The taxpayer's TIN.
    TaxpayerType:
      type: string
      enum:
        - Business
        - Individual
      description: Whether the taxpayer is a business (EIN) or an individual (SSN).
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The access token from the client credentials grant, sent as a Bearer
        credential.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.