Pay data structure

Learn about the structure of pay data available in the /payouts and /income-totals endpoints.

Argyle allows you to retrieve detailed income data for all connected payroll accounts.

The /payouts endpoint provides information from individual paystubs.

The /income-totals endpoint provides total pay amounts from all paystubs for each calendar year.


The /payouts endpoint provides machine-readable, normalized versions of traditional paystubs. These digital paystubs are returned as payout objects.

Each payout object contains summary information, paystub totals, year-to-date amounts, information from each paystub entry, and gross pay totals by type.


Year-to-date amounts in the payout object are provided as they appear on paystubs. They are not calculated values.

A complete list of available information provided by the /payouts endpoint can be found in Payouts, including a full sample JSON object.

Structure of payout objects

Structure of payout objectsStructure of payout objects

Structure of gross_pay_list, deduction_list, and tax_list

gross_pay_list, deduction_list, and tax_list contain information from individual entries on a paystub.

Structure of gross_pay_list, deduction_list, and tax_listStructure of gross_pay_list, deduction_list, and tax_list

Structure of gross_pay_list_totals

Paystub entries contained in gross_pay_list are added together based on their type attribute and presented in the gross_pay_list_totals object.

Structure of gross_pay_list_totalsStructure of gross_pay_list_totals


The /income-totals endpoint provides total pay amounts gathered from all paystubs for each available calendar year.

Information regarding users’ total yearly compensation is fundamental in many use cases. Unfortunately, paystubs often omit this information or provide it only for some but not all entries. Through the /income-totals endpoint, Argyle aggregates this yearly income information in a standardized way.

Structure of the income-totals endpoint

Yearly pay information is returned as a series of objects representing each calendar year.

Structure of the income-totals endpointStructure of the income-totals endpoint

A full sample JSON object can be found in Income-totals.

Connecting /payouts and /income-totals

  • income_totals.gross_pay corresponds to payout.gross_pay_list_totals.
  • income_totals.deductions is based on payout.deductions and payout.deductions_ytd, with income_totals.taxes and income_totals.net_pay following the same approach.
  • income_totals.reimbursements and income_totals.fees correspond to payout.reimbursements and payout.fees, respectively.