> ## 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.

# Get a return transcript

> GET /transcripts/return/{id}

Returns one return transcript, its sections grouped in `forms` by return, schedule or form.
See the [Transcripts overview](https://docs.taxrock.com/api-reference/transcripts/overview.md).


## OpenAPI

````yaml api-reference/openapi-direct.json GET /transcripts/return/{id}
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:
  /transcripts/return/{id}:
    get:
      tags:
        - Transcripts
      summary: Get a return transcript
      description: >-
        Returns one return transcript, its sections grouped by return, schedule
        or form.
      operationId: getReturnTranscript
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            The transcript's `id`, from the taxpayer's list of return
            transcripts.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The transcript.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnTranscript'
              example:
                id: 00000000-0000-4000-8000-000000000001
                taxpayerId: 00000000-0000-4000-8000-0000000000a2
                form:
                  name: '1040'
                  taxYear: 2023
                  taxPeriod: 12
                  taxPeriodName: Annual
                createdAt: '2024-05-02T14:03:51Z'
                updatedAt: '2026-10-06T18:40:20Z'
                filed: true
                receivedDate: '2024-04-15'
                adjustedGrossIncome: 397195
                filingStatus: MarriedFilingJoint
                filingStatusRaw: Married Taxpayer Filing Joint Return
                forms:
                  - code: Form1040
                    occurrence: 1
                    sections:
                      - name: ''
                        lineItems:
                          - label: Request Date
                            column: null
                            rawValue: 10-06-2026
                            type: Date
                            value: '2026-10-06'
                        subsections: []
                      - name: ''
                        lineItems:
                          - label: SSN provided
                            column: null
                            rawValue: 000-00-0000
                            type: String
                            value: 000-00-0000
                          - label: Report for Tax Period Ending
                            column: null
                            rawValue: 12-31-2023
                            type: Date
                            value: '2023-12-31'
                        subsections: []
                      - name: Income
                        lineItems:
                          - label: Adjusted gross income
                            column: null
                            rawValue: $397,195.00
                            type: Currency
                            value: 397195
                        subsections: []
                  - code: ScheduleC
                    occurrence: 1
                    sections:
                      - name: >-
                          Schedule C - Profit or Loss From Business (Occurrence
                          #: 1)
                        lineItems:
                          - label: Social Security Number
                            column: null
                            rawValue: 000-00-0000
                            type: String
                            value: 000-00-0000
                          - label: Employer ID number
                            column: null
                            rawValue: 00-0000000
                            type: String
                            value: 00-0000000
                          - label: Business name
                            column: null
                            rawValue: EXAMPLE CONSULTING
                            type: String
                            value: EXAMPLE CONSULTING
                          - label: Gross receipts or sales
                            column: null
                            rawValue: $120,000.00
                            type: Currency
                            value: 120000
                        subsections: []
                  - code: Form8995
                    occurrence: 1
                    sections:
                      - name: Form 8995 - A/8995 Qualified Business Income Deduction
                        lineItems:
                          - label: Qualified business income deduction
                            column: null
                            rawValue: $21,000.00
                            type: Currency
                            value: 21000
                        subsections: []
        '400':
          description: The `id` is not a valid UUID. `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.
        '404':
          description: >-
            The transcript does not exist or is outside the credential's
            organization. `error` is `not_found`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
              example:
                error: not_found
                message: Transcript not found.
components:
  schemas:
    ReturnTranscript:
      type: object
      description: One return transcript.
      required:
        - id
        - taxpayerId
        - form
        - createdAt
        - updatedAt
        - filed
        - receivedDate
        - adjustedGrossIncome
        - filingStatus
        - filingStatusRaw
        - forms
      properties:
        id:
          type: string
          format: uuid
          description: The transcript's id.
        taxpayerId:
          type: string
          format: uuid
          description: The taxpayer's id.
        form:
          $ref: '#/components/schemas/TranscriptForm'
        createdAt:
          type: string
          format: date-time
          description: When TaxRock created this transcript record, in UTC.
        updatedAt:
          type: string
          format: date-time
          description: When TaxRock last updated this transcript record, in UTC.
        filed:
          type: boolean
          description: Whether the transcript shows a filed return.
        receivedDate:
          type:
            - string
            - 'null'
          format: date
          description: The date the return was received.
        adjustedGrossIncome:
          type:
            - number
            - 'null'
          description: Adjusted gross income as filed.
        filingStatus:
          anyOf:
            - $ref: '#/components/schemas/FilingStatus'
            - type: 'null'
          description: >-
            The printed filing status as one of five values. Null when none is
            printed or it does not match one.
        filingStatusRaw:
          type:
            - string
            - 'null'
          description: The filing status as printed.
        forms:
          type: array
          items:
            $ref: '#/components/schemas/ReturnForm'
          description: The transcript's sections, grouped by return, schedule or form.
    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.
    NotFoundError:
      type: object
      description: The 404 body of the transcript endpoints.
      required:
        - error
        - message
      properties:
        error:
          type: string
          enum:
            - not_found
          description: The error code.
        message:
          type: string
          description: Human-readable explanation.
    TranscriptForm:
      type: object
      description: The form, year and period a transcript covers.
      required:
        - name
        - taxYear
        - taxPeriod
        - taxPeriodName
      properties:
        name:
          type: string
          description: The form name in upper case, e.g. `1040`, `941` or `ALL FORMS`.
        taxYear:
          type: integer
          description: The tax year.
        taxPeriod:
          type: integer
          description: >-
            The period's last month: 12 for an annual form, or 3, 6, 9 or 12 for
            a quarterly one.
        taxPeriodName:
          type: string
          description: '`Annual`, or `Q1` to `Q4`.'
    FilingStatus:
      type: string
      enum:
        - Single
        - MarriedFilingJoint
        - MarriedFilingSeparate
        - HeadOfHousehold
        - QualifyingSurvivingSpouse
      description: A federal filing status.
    ReturnForm:
      type: object
      description: The sections of one return, schedule or form on a return transcript.
      required:
        - code
        - occurrence
        - sections
      properties:
        code:
          $ref: '#/components/schemas/ReturnFormCode'
        occurrence:
          type: integer
          description: >-
            Which instance of this return, schedule or form the entry is, from
            1.
        sections:
          type: array
          items:
            $ref: '#/components/schemas/ReturnSection'
          description: The entry's sections.
    ReturnFormCode:
      type: string
      enum:
        - Unrecognized
        - Form1040
        - Form1040NR
        - Form1065
        - Form1120
        - Form1120L
        - Form1120S
        - Form940
        - Form941
        - ScheduleA
        - ScheduleB
        - ScheduleC
        - ScheduleD
        - ScheduleE
        - ScheduleEIC
        - ScheduleF
        - ScheduleH
        - ScheduleJ
        - ScheduleK
        - ScheduleL
        - ScheduleM2
        - ScheduleR
        - ScheduleSE
        - Form461
        - Form1116
        - Form2441
        - Form2555
        - Form3800
        - Form4136
        - Form4137
        - Form4255
        - Form4626
        - Form4684
        - Form4797
        - Form4835
        - Form4952
        - Form5329
        - Form5405
        - Form5695
        - Form5884B
        - Form6198
        - Form6251
        - Form6252
        - Form8283
        - Form8606
        - Form8825
        - Form8839
        - Form8853
        - Form8863
        - Form8867
        - Form8888
        - Form8889
        - Form8936
        - Form8941
        - Form8958
        - Form8959
        - Form8960
        - Form8962
        - Form8978
        - Form8995
        - Form8997
      description: >-
        The return, schedule or form a `forms` entry holds, e.g. `Form1040`,
        `ScheduleC` or `Form8959`:


        - `Form2555`: Form 2555 or 2555-EZ.

        - `Form8995`: Form 8995 or 8995-A.

        - `ScheduleK`: Schedule K of the transcript's return.

        - `Unrecognized`: Sections not assigned to a listed form.


        Treat a code you do not know as `Unrecognized`.
    ReturnSection:
      type: object
      description: One printed block of a return transcript.
      required:
        - name
        - lineItems
        - subsections
      properties:
        name:
          type: string
          description: The heading as printed. Empty when none is printed.
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/ReturnLineItem'
          description: The section's lines.
        subsections:
          type: array
          items:
            $ref: '#/components/schemas/ReturnSection'
          description: The sections under this one's heading.
    ReturnLineItem:
      type: object
      description: One line of a return transcript section.
      required:
        - label
        - column
        - rawValue
        - type
        - value
      properties:
        label:
          type: string
          description: The line's label as printed.
        column:
          type:
            - string
            - 'null'
          description: The column header above the value. Null when the line has one value.
        rawValue:
          type: string
          description: The value as printed.
        type:
          $ref: '#/components/schemas/LineItemType'
        value:
          type:
            - number
            - string
            - 'null'
          description: >-
            The value: a number for `Currency`, `Percent` and `Int`, otherwise a
            string.
    LineItemType:
      type: string
      enum:
        - Currency
        - Date
        - Percent
        - Int
        - Decimal
        - String
      description: |-
        The kind of value a line holds:

        - `Currency`: an amount in dollars.
        - `Date`: a date, `YYYY-MM-DD`.
        - `Percent`: a percentage, e.g. `25` for 25 percent.
        - `Int`: a whole number.
        - `Decimal`: a decimal number, e.g. `"1234.5678"`.
        - `String`: text.
  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.