The Income object

The Income response aggregates income data from all connected payroll providers and bank accounts. Employment records share a common shape and are merged and deduplicated, with a data_source field to identify the origin.

Query parameters

Parameter	Type	Default	Description
days	integer	`90`	Days of income history to include (1-365). Pay statements are filtered to this window.

Response attributes

Attribute	Type	Description
employments	array of objects	Combined employment and income records from all connected sources

Employment fields

Field	Type	Description
data_source	string	`payroll` or `financial_accounts`
provider	string	Data provider (e.g. `adp`, `chase`)
company	object	Income source: `{name, address, phone, ein}`. Payroll adds `logo_url` when available; bank-derived sources populate `name` only.
income	string \| null	Income amount
income_unit	string	Unit for `income`, e.g. `YEARLY`
pay_rate	string \| null	Amount per pay period
pay_frequency	string \| null	Truv frequency code: `W` weekly, `BW` biweekly, `SM` semi-monthly, `M` monthly, `A` annual
statements	array of objects	Pay statements within the requested `days` window (see below)
is_active	boolean	Whether the income source is currently active
job_title / job_type	string \| null	Title and employment type (payroll only)
start_date / end_date	string \| null	Employment date range
bank_income_category	string \| null	Income category, set when `data_source=financial_accounts`

Each statements[] entry includes pay_date and net_pay; payroll statements also carry gross_pay, hours, and an earnings breakdown, while bank-derived statements leave those null. Payroll employments are passed through from the provider and may include additional provider-specific fields beyond those listed above.

Endpoints

Get income

Example response

{
  "employments": [
    {
      "data_source": "payroll",
      "provider": "adp",
      "company": {
        "name": "Acme Corp",
        "address": { "street": "123 Main St", "city": "Austin", "state": "TX", "zip": "78701", "country": "US" },
        "phone": null,
        "ein": "12-3456789",
        "logo_url": "https://logos.mytruv.com/acme.png"
      },
      "income": "120000.00",
      "income_unit": "YEARLY",
      "pay_rate": "4615.38",
      "pay_frequency": "BW",
      "is_active": true,
      "job_title": "Software Engineer",
      "job_type": "F",
      "start_date": "2022-01-15",
      "end_date": null,
      "statements": [
        {
          "pay_date": "2026-06-15",
          "net_pay": "3800.00",
          "gross_pay": "4615.38",
          "hours": "80",
          "earnings": []
        }
      ]
    },
    {
      "data_source": "financial_accounts",
      "provider": "chase",
      "company": {
        "name": "Freelance Income",
        "address": { "street": null, "city": null, "state": null, "zip": null, "country": null },
        "phone": null,
        "ein": null
      },
      "income": "24000.00",
      "income_unit": "YEARLY",
      "pay_rate": "2000.00",
      "pay_frequency": "M",
      "is_active": true,
      "job_title": null,
      "job_type": null,
      "start_date": "2024-03-01",
      "end_date": null,
      "bank_income_category": "freelance",
      "statements": [
        { "pay_date": "2026-06-01", "net_pay": "2000.00", "gross_pay": null, "hours": null, "earnings": [] }
      ]
    }
  ]
}

​Query parameters

​Response attributes

​Employment fields

​Endpoints

​Example response

Query parameters

Response attributes

Employment fields

Endpoints

Example response