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

# List Tradelines

> Returns a paginated list of tradelines for the authenticated partner.



## OpenAPI

````yaml GET /tradelines
openapi: 3.0.3
info:
  title: Cove Data Furnishing API
  description: >
    A generic data furnishing API that accepts any recurring payment type

    (rent, child support, alimony, utilities, etc.) and reports it to credit

    bureaus (Equifax, TransUnion, Experian) in Metro 2 format.


    ## Authentication

    All requests require an `x-api-key` header with a valid API key.

    - `sk_live_*` keys operate in production mode.

    - `sk_test_*` keys operate in sandbox mode (data is created but never
    reaches bureaus).


    ## Amounts

    All monetary amounts are in **cents** (USD integers). For example, $45.00 =
    `4500`.


    ## Dates

    All date fields use `YYYY-MM-DD` format.


    ## Integration Guide

    For a full walkthrough with curl examples, see the

    [Integration Guide](./integration-guide.md).
  version: 1.0.0
  contact:
    name: Cove
    url: https://cove.dev
  license:
    name: Proprietary
    url: https://cove.dev/terms
servers:
  - url: https://vvdufluovypptsnkihyv.supabase.co/functions/v1
    description: Current deployment (Supabase)
  - url: https://furnish.cove.dev/v1
    description: Production (coming soon)
  - url: https://sandbox-furnish.cove.dev/v1
    description: Sandbox (coming soon)
security:
  - ApiKeyAuth: []
tags:
  - name: Consumers
    description: >-
      Manage consumer records (PII). Consumers represent the individuals whose
      payments are being reported to credit bureaus.
  - name: Tradelines
    description: >-
      Manage tradelines — ongoing payment obligations being reported to credit
      bureaus. Each tradeline belongs to a consumer and tracks a specific
      payment type.
  - name: Payments
    description: >-
      Report monthly payments against tradelines. Each payment automatically
      updates the tradeline's account status, balance, and 24-month payment
      history.
  - name: Submissions
    description: >-
      Track and manage bureau submission status. Submissions are created
      automatically or via manual trigger.
  - name: Webhooks
    description: Webhook event types and payloads delivered to your configured webhook URL.
paths:
  /tradelines:
    get:
      tags:
        - Tradelines
      summary: List tradelines
      description: Returns a paginated list of tradelines for the authenticated partner.
      operationId: listTradelines
      parameters:
        - name: consumer_id
          in: query
          description: Filter by consumer UUID
          schema:
            type: string
            format: uuid
        - name: payment_type
          in: query
          description: Filter by payment type
          schema:
            $ref: '#/components/schemas/PaymentType'
        - name: status
          in: query
          description: Filter by account status
          schema:
            $ref: '#/components/schemas/AccountStatus'
        - name: is_active
          in: query
          description: Filter by active state (true or false)
          schema:
            type: boolean
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/per_page'
      responses:
        '200':
          description: Paginated list of tradelines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTradelines'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    PaymentType:
      type: string
      description: Type of recurring payment being reported
      enum:
        - rent
        - child_support
        - alimony
        - utility
        - medical
        - insurance
        - subscription
        - bill_pay
        - loan
        - education
        - dependent_care
        - shared_expenses
        - custom
    AccountStatus:
      type: string
      description: >-
        Current status of the tradeline account (auto-computed from payment
        reports)
      enum:
        - current
        - late_30
        - late_60
        - late_90
        - late_120
        - late_150
        - late_180_plus
        - paid_in_full
        - closed
        - transferred
        - account_in_dispute
    PaginatedTradelines:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Tradeline'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Tradeline:
      type: object
      properties:
        id:
          type: string
          format: uuid
        consumer_id:
          type: string
          format: uuid
        partner_id:
          type: string
          format: uuid
        payment_type:
          $ref: '#/components/schemas/PaymentType'
        payment_type_label:
          type: string
          nullable: true
        external_account_id:
          type: string
          nullable: true
        account_opened_date:
          type: string
          format: date
        account_closed_date:
          type: string
          format: date
          nullable: true
        payment_amount:
          type: integer
          description: In cents
        payment_frequency:
          type: string
        credit_limit:
          type: integer
          nullable: true
          description: In cents
        highest_balance:
          type: integer
          nullable: true
          description: In cents
        original_loan_amount:
          type: integer
          nullable: true
          description: In cents
        account_status:
          $ref: '#/components/schemas/AccountStatus'
        current_balance:
          type: integer
          description: In cents
        amount_past_due:
          type: integer
          description: In cents
        ecoa_code:
          type: string
        metro2_account_type:
          type: string
        payment_history:
          type: string
          description: >-
            24-char Metro 2 payment history (newest first). 0=current, 1=30d,
            2=60d, 3=90d, 4=120d, 5=150d, 6=180d+
        date_of_first_delinquency:
          type: string
          format: date
          nullable: true
          description: Set on first non-current payment
        report_to_bureaus:
          type: array
          items:
            type: string
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              enum:
                - VALIDATION_ERROR
                - AUTHENTICATION_ERROR
                - AUTHORIZATION_ERROR
                - NOT_FOUND
                - CONFLICT
                - RATE_LIMITED
                - INTERNAL_ERROR
            message:
              type: string
              description: Human-readable error description
            field:
              type: string
              description: >-
                Dot-notation path to the field that caused the error (e.g.,
                address.state). Only present when a specific field is
                responsible.
            request_id:
              type: string
              format: uuid
  parameters:
    page:
      name: page
      in: query
      description: Page number (1-indexed)
      schema:
        type: integer
        default: 1
        minimum: 1
    per_page:
      name: per_page
      in: query
      description: Number of records per page
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
  responses:
    AuthenticationError:
      description: Authentication error (401)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: AUTHENTICATION_ERROR
              message: Missing x-api-key header
              request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44
    InternalError:
      description: Internal server error (500)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: An unexpected error occurred
              request_id: 4e9024e3-125d-4d08-a392-4fa34f6bda44
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >
        API key in the format `sk_live_<token>` (production) or
        `sk_test_<token>` (sandbox).

        Contact Cove to obtain your API key.

````