Income Report

Retrieve the most recent bank income report

Changed on

Retrieves the most recent bank income report for the specified link. This endpoint returns the latest generated report containing transaction-based income analysis and verification data.

get/v1/links/{link_id}/income/transactions/reports/

Request

  • Base URL
    https://prod.truv.com
  • URL
    https://prod.truv.com/v1/links/{link_id}/income/transactions/reports/
  • Auth
    API key in header X-Access-Client-Id and API key in header X-Access-Secret

Query parameters

show_fraud_reasonsboolean

Set to true to include fraud_reasons in the response. The field is omitted by default.

Response

statusstring required

Status of the report. Common values: success, processing, no transactions found, not found, failed. Additional upstream statuses may be passed through.

completed_atstring date-time nullable required

Timestamp when the report was completed.

days_requestedinteger required

The specific duration in days for which the report is requested to be generated.

tracking_infostring nullable

Additional optional identifier passed by user.

providerstring required

Data provider ID.

access_tokenstring uuid

Access token of the existing link.

companiesstring[]

Names of the companies person works for.

is_suspiciousboolean

Flag to indicate if the data from the source is suspicious. E.g. fraud detected in uploaded documents or SSN of the user does not match with the data

pdf_reportstring uri nullable

URL of the PDF report file

Example response

{
  "status": "success",
  "completed_at": "2022-05-04T11:30:00Z",
  "days_requested": 60,
  "access_token": "99dd17074ac94aa9ace2621d657c7610",
  "accounts": [
    {
      "id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "created_at": "2022-05-04T11:30:00Z",
      "updated_at": "2022-05-04T12:00:00Z",
      "type": "CHECKING",
      "subtype": "MONEY_MARKET",
      "nickname": "My account",
      "days_available": 365,
      "owners": [
        {
          "id": "2b623fa2fa9e49cea17d9692caa884c5",
          "full_name": "John Doe",
          "email": "john.doe@example.com",
          "phone": "14155554193",
          "address": {
            "street": "1 Morgan Ave",
            "city": "Los Angeles",
            "state": "CA",
            "zip": "90210",
            "country": "US"
          },
          "relation_type": "PRIMARY"
        }
      ]
    }
  ],
  "income": [
    {
      "start_date": "2022-05-04",
      "end_date": "2022-05-04",
      "account_id": "24d7e80942ce4ad58a93f70ce4115f5c",
      "income_description": "Paycheck",
      "income_category": "PAYCHECK",
      "pay_frequency": "SM",
      "next_payment_date": "2022-06-01",
      "total_amount": "200.31",
      "iso_currency_code": "USD",
      "transaction_count": 1,
      "historical_summary": [
        {
          "start_date": "2022-05-04",
          "end_date": "2022-05-04",
          "total_amount": "200.31",
          "iso_currency_code": "USD",
          "transactions": [
            {
              "amount": "200.31",
              "iso_currency_code": "USD",
              "date": "2022-05-04",
              "transaction_id": "7d4fcb86b81a4880955beea558092391"
            }
          ]
        }
      ],
      "historical_average_monthly_income": "10000.00",
      "historical_average_monthly_gross_income": "12000.00",
      "forecasted_average_monthly_income": "10000.00",
      "avg_deposit_amount": "5000.00",
      "avg_gross_deposit_amount": "6000.00"
    }
  ],
  "summary": {
    "start_date": "2022-05-04",
    "end_date": "2022-05-04",
    "income_sources_count": 2,
    "income_categories_count": 1,
    "income_transactions_count": 17,
    "total_amount": "200.31",
    "iso_currency_code": "USD",
    "historical_average_monthly_gross_income": "200.31",
    "historical_average_monthly_income": "200.31",
    "forecasted_average_monthly_income": "200.31",
    "historical_annual_gross_income": "200.31",
    "historical_annual_income": "200.31",
    "forecasted_annual_income": "200.31"
  },
  "fraud_reasons": [
    {
      "code": "editing_software_detected",
      "message": "Document metadata identifies editing software.",
      "severity": "high",
      "document_ids": [
        "d1f3a6e0b1c24f6c9b3e2a7d5c8e9f01"
      ],
      "uploaded_file_ids": [
        "9ac0b2d4e6f84a1c8e3b5d7f9a1c3e5b"
      ],
      "details": {
        "software": [
          "Adobe Photoshop 25.0 (Windows)"
        ]
      },
      "task_id": "48427a36d43c4d5aa6324bc06c692456",
      "created_at": "2026-10-20T14:03:11Z"
    }
  ],
  "pdf_report": "https://cdn.truv.com/report.pdf"
}

Changes

    • info

      added the new optional query request parameter show_fraud_reasons

    • info

      added the optional property to the response with the status

    • info

      the // response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the // response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the // response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the // response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the // response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the //// response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the ////// response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the // response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status

    • info

      the / response's property pattern ^-?\d{1,10}\.\d{2}$ was added for the status