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

> ## Agent Instructions
> Melso MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# List tax returns

> Lists the company's returns: the ones Melso calculated (drafts, approved and filed) and the reminder forms marked filed.

<Check>
  **Live capability.** Melso runs this in production today. Partner keys reach it once your partner account is enabled. See [Availability](/api/availability).
</Check>

While a
filing window is open, a draft is recalculated from the company's
records, and each change raises its `version`. Without an active tax
service, the list carries estimates (`is_estimate` `true`) instead of
drafts.


## OpenAPI

````yaml api/openapi.yaml GET /companies/{company_id}/tax-returns
openapi: 3.1.0
info:
  title: Melso API
  version: 1.0.0-preview
  summary: Spanish tax and labour compliance for the companies on your platform.
  description: |
    The Melso API lets an HR, payroll, banking or ERP platform run the
    Spanish tax and labour obligations of the companies it serves: invoices,
    books, tax returns, Social Security and employment notifications.

    Melso calculates and prepares. A person at the company approves the exact
    version. Melso's professionals file under the company's representation, and
    the filing is proven only by the administration's reference and receipt.

    Every operation states its availability in `x-melso-status`:

    - `live`: Melso runs this capability in production today. Partner keys
      reach it once a partner account is enabled.
    - `preview`: a contract proposed to design partners. Not callable yet.

    `x-melso-actor: person` marks a decision a signed-in person makes in
    Melso; a partner sends them the approval link instead.
  contact:
    name: Melso partnerships
    email: hello@melso.ai
    url: https://docs.melso.ai/api/overview
servers:
  - url: https://api.melso.ai/v1
    description: API. Keys and access are issued per partner.
security:
  - partnerKey: []
tags:
  - name: Companies
    description: The companies you operate for, their fiscal profile and hosted onboarding.
  - name: Mandates
    description: >-
      The company's representation of Melso before the AEAT, the TGSS and the
      SEPE.
  - name: Webhook endpoints
    description: Where Melso sends signed events about your companies.
  - name: Invoicing setup
    description: Registration of the company as a VERI*FACTU or TicketBAI invoice issuer.
  - name: Customers
    description: The company's invoice customers.
  - name: Invoices
    description: >-
      Drafts, approval, legal registration, delivery and payment of the
      company's invoices.
  - name: Expenses
    description: >-
      Purchase invoices and receipts, with their AEAT category and
      deductibility.
  - name: Income
    description: Income invoiced outside Melso.
  - name: Documents
    description: >-
      Files the company gives Melso, and Melso's structured reading of an
      invoice or receipt.
  - name: Banking
    description: >-
      Bank accounts, movements, statements and reconciliation with invoices and
      expenses.
  - name: Accounting
    description: Journal, imported books and the company's financial statements.
  - name: Tax calendar
    description: The forms the company must file, with their periods and deadlines.
  - name: Tax returns
    description: The returns Melso calculates, their approval and their filing.
  - name: Corporate tax
    description: The year's corporate tax (modelo 200) and its instalments (modelo 202).
  - name: Tax estimates
    description: What the company should set aside for taxes, as of today.
  - name: Cases
    description: Gestiones, the procedures Melso's professionals carry out for the company.
  - name: Administration notifications
    description: Electronic notifications from the administration to the company.
  - name: Certificates
    description: >-
      Official certificates such as being up to date with the AEAT or the Social
      Security.
  - name: Employees
    description: The people the company employs.
  - name: Payroll runs
    description: >-
      The payroll results your platform calculated, for Melso to settle and
      declare.
  - name: Social Security
    description: >-
      Affiliation (altas, bajas and variaciones) and monthly contribution
      settlements.
  - name: Employment notifications
    description: >-
      Contrat@ contract notifications and Certific@2 company certificates to the
      SEPE.
paths:
  /companies/{company_id}/tax-returns:
    parameters:
      - $ref: '#/components/parameters/CompanyId'
    get:
      tags:
        - Tax returns
      summary: List tax returns
      description: |
        Lists the company's returns: the ones Melso calculated (drafts,
        approved and filed) and the reminder forms marked filed. While a
        filing window is open, a draft is recalculated from the company's
        records, and each change raises its `version`. Without an active tax
        service, the list carries estimates (`is_estimate` `true`) instead of
        drafts.
      operationId: listTaxReturns
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: model
          in: query
          description: Only this form, such as `303`.
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/TaxReturnStatus'
      responses:
        '200':
          description: Returns.
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - next_cursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxReturn'
                  next_cursor:
                    $ref: '#/components/schemas/NextCursor'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    CompanyId:
      name: company_id
      in: path
      required: true
      description: >-
        The company's ID. Every company-scoped call works in exactly this
        company.
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: Page size.
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 50
    Cursor:
      name: cursor
      in: query
      description: The `next_cursor` of the previous page.
      schema:
        type: string
  schemas:
    TaxReturnStatus:
      type: string
      enum:
        - draft
        - approved
        - filed
      description: >-
        `draft`: calculated, still recalculated from the records. `approved`:
        the owner authorized this exact version. `filed`: filed, with the
        administration's reference and receipt when Melso filed it.
    TaxReturn:
      type: object
      required:
        - id
        - model
        - period
        - status
        - amount
        - is_estimate
      properties:
        id:
          type: string
          description: The return's UUID, or `estimate:<model>:<period>` for an estimate.
        model:
          type: string
          description: >-
            The form. Melso calculates `303`, `130`, `111`, `115`, `190`, `180`,
            `347`, `349` and `390` today; a reminder form marked filed has its
            own model.
        period:
          $ref: '#/components/schemas/Period'
        status:
          $ref: '#/components/schemas/TaxReturnStatus'
        is_estimate:
          type: boolean
          description: >-
            An estimate has an amount only. It has no boxes, no version and no
            approval.
        amount:
          $ref: '#/components/schemas/Amount'
          description: >-
            The result. Negative to offset or refund (303); `0.00` for an
            informative return.
        version:
          type:
            - integer
            - 'null'
          description: >-
            Raised on every recalculation that changes the draft. Approval needs
            the exact version.
        approved_version:
          type:
            - integer
            - 'null'
        approved_at:
          type:
            - string
            - 'null'
          format: date-time
        deadline:
          type: string
          format: date
        direct_debit_deadline:
          type:
            - string
            - 'null'
          format: date
        boxes:
          type: array
          items:
            $ref: '#/components/schemas/TaxReturnBox'
        records:
          type: array
          items:
            $ref: '#/components/schemas/TaxReturnRecord'
        review:
          type: array
          description: What to check before approving.
          items:
            type: string
            enum:
              - missing_tax_id
              - cadastral_reference
              - eu_key_assumed
              - rates_assumed
              - volume_split
        unconfirmed_expenses:
          type: integer
          description: Expenses in the return that are not yet confirmed as deductible.
        filed_at:
          type:
            - string
            - 'null'
          format: date-time
        filing:
          description: Preview. The administration's evidence, when Melso filed the return.
          oneOf:
            - $ref: '#/components/schemas/FilingReceipt'
            - type: 'null'
        recalculated:
          type:
            - object
            - 'null'
          description: >-
            For a filed return whose records changed afterwards, what it would
            be today. A difference may need a complementary or corrective
            return.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    NextCursor:
      type:
        - string
        - 'null'
      description: Pass it as `cursor` for the next page. `null` on the last page.
    Period:
      type: string
      pattern: ^[0-9]{4}(-Q[1-4]|-(0[1-9]|1[0-2])|-[1-3]P)?$
      description: >-
        A year (`2026`), a quarter (`2026-Q3`), a month (`2026-09`) or an
        instalment (`2026-1P`).
      examples:
        - 2026-Q3
    Amount:
      type: string
      pattern: ^-?[0-9]+\.[0-9]{2}$
      description: >-
        An amount in euros as a decimal string with two decimals, such as
        `"121.00"`.
      examples:
        - '121.00'
    TaxReturnBox:
      type: object
      properties:
        box:
          type: string
          description: >-
            The form's box number, such as `27`. Empty for an internal working
            line.
        key:
          type: string
          description: What the box holds.
        amount:
          $ref: '#/components/schemas/Amount'
    TaxReturnRecord:
      type: object
      description: One line of an informative return (190, 180, 347, 349).
      properties:
        tax_id:
          type: string
        name:
          type: string
        country:
          type: string
        key:
          type: string
          description: >-
            The record key: A or B for the 347, I or S for the 349, A or G for
            the 190.
        amount:
          $ref: '#/components/schemas/Amount'
        withheld:
          $ref: '#/components/schemas/Amount'
        quarters:
          type: array
          items:
            $ref: '#/components/schemas/Amount'
          maxItems: 4
        missing:
          type: array
          items:
            type: string
            enum:
              - tax_id
              - cadastral_reference
    FilingReceipt:
      type: object
      required:
        - filed_at
        - reference
      properties:
        filed_at:
          type: string
          format: date-time
        reference:
          type: string
          description: The administration's filing reference (número de justificante).
        csv:
          type: string
          description: The código seguro de verificación printed on the receipt.
        receipt:
          $ref: '#/components/schemas/Document'
        filed_by:
          type: string
          enum:
            - melso
            - company
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: What went wrong, for a person to read.
        code:
          type: string
          description: >-
            A stable code to branch on, such as `invoicing_not_ready` or
            `version_conflict`.
        request_id:
          type: string
          description: Quote it when you contact Melso.
    Document:
      type: object
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
        content_type:
          type: string
        size_bytes:
          type: integer
        url:
          type: string
          format: uri
          description: A short-lived download URL.
  responses:
    Unauthorized:
      description: The key is missing, revoked or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid token
            code: unauthorized
            request_id: req_01JAB3K9X2
    NotFound:
      description: No such object in this company, or the company is not one of yours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invoice not found
            code: not_found
            request_id: req_01JAB3K9X2
  securitySchemes:
    partnerKey:
      type: http
      scheme: bearer
      description: |
        Your partner secret key, `mk_live_…` for real companies or `mk_test_…`
        for test companies. Keep it on your servers. See
        [Authentication](/api/authentication).

````

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