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

# Income Totals

> Learn about the /income-totals endpoint.

Learn about the `/income-totals` endpoint.

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

![High level structure of the income totals object.](https://res.cloudinary.com/argyle-media/image/upload/f_auto/v1683741432/docs-2023/API%20Endpoints/Income_totals2)

## The Income totals object

Yearly pay information is returned as a series of objects, each representing a calendar year. These objects are returned in the `income_totals` array. Each object contains the following attributes:

### Attributes

* `account` (string (uuid), optional)
* `period` (string, optional): Calendar year.
* `gross_pay` (object, optional): Contains the amount of gross pay earned in the calendar year, in total and by category.

```json theme={}

{
"account": "05e9e043-87a2-4e7f-83b1-9181dcc1e784",
"last_payout_date": "2022-08-29",
"period_start_date": "2021-01-15",
"period_end_date": "2022-08-29",
"income_totals": [
{
"period": "2022",
"currency": "USD",
"gross_pay": {
"total": "35020.39",
"base": "21231.02",
"overtime": "1231.12",
"bonus": "12312.01",
"commission": "123.12",
"other": "123.12",
},
"reimbursements": "123.12",
"deductions": "123.12",
"taxes": "12345.12",
"fees": "12.01",
"net_pay": "22417.02",
},
{
"period": "2021",
"currency": "USD",
"gross_pay": {
"total": "35020.39",
"base": "21231.02",
"overtime": "1231.12",
"bonus": "12312.01",
"commission": "123.12",
"other": "123.12",
},
"reimbursements": "123.12",
"deductions": "123.12",
"taxes": "12345.12",
"fees": "12.01",
"net_pay": "22417.02",
},
{
"period": "2021",
"currency": "GBP",
"gross_pay": {
"total": "35020.39",
"base": "21231.02",
"overtime": "1231.12",
"bonus": "12312.01",
"commission": "123.12",
"other": "123.12",
},
"reimbursements": "123.12",
"deductions": "123.12",
"taxes": "12345.12",
"fees": "12.01",
"net_pay": "22417.02",
}
]
},
null,
2

```

<RefSubLayout.Divider />

## List income-totals

**GET** `/v1/income-totals`

<Note>
  A query parameter (`account` *or* `user`) MUST be used when listing income-totals.
</Note>

* List all income-totals by calendar year, from newest to oldest.
* This request returns an object with a `results` property that contains an array of objects for each account that include the account ID, `last_payout_date`, `period_start_date`, `period_end_date`, and `income_totals` object.

### Query parameters

<Tabs>
  <Tab title="curl">
    ```bash theme={}
    curl --request GET \\
    --url https://api.argyle.com/v1/income-totals?{account}={id} \\
    --header 'accept: application/json' \\
    --header 'content-type: application/json'

    ```
  </Tab>

  <Tab title="python">
    ```python theme={}
    import requests
    url = "https://api.argyle.com/v1/income-totals?{account}={id}"
    headers = {
    "accept": "application/json",
    "content-type": "application/json"
    }
    response = requests.get(url, headers=headers)
    ```
  </Tab>
</Tabs>

```json theme={}

[
  {
"account": "05e9e043-87a2-4e7f-83b1-9181dcc1e784",
"last_payout_date": "2022-08-29",
"period_start_date": "2021-01-15",
"period_end_date": "2022-08-29",
"income_totals": [
  {
"period": "2022",
"currency":"USD",
"gross_pay": {
"total": "35020.39",
"base": "21231.02",
"overtime":"1231.12",
"bonus":"12312.01",
"commission":"123.12",
"other":"123.12",
},
"reimbursements": "123.12",
"deductions": "123.12",
"taxes": "12345.12",
"fees": "12.01",
"net_pay": "22417.02",		 
  },
  {
"period": "2021",
"currency":"USD",
"gross_pay": {
"total": "35020.39",
"base": "21231.02",
"overtime":"1231.12",
"bonus":"12312.01",
"commission":"123.12",
"other":"123.12",
},
"reimbursements": "123.12",
"deductions": "123.12",
"taxes": "12345.12",
"fees": "12.01",
"net_pay": "22417.02",
  },
  {
"period": "2021",
"currency":"GBP",
"gross_pay": {
"total": "35020.39",
"base": "21231.02",
"overtime":"1231.12",
"bonus":"12312.01",
"commission":"123.12",
"other":"123.12",
},
"reimbursements": "123.12",
"deductions": "123.12",
"taxes": "12345.12",
"fees": "12.01",
"net_pay": "22417.02",
  }
]
  }
],
null,
2

```