Learn about the /payouts endpoint.
The payout object
payout objectpayouts are machine-readable, normalized versions of traditional paystubs. Each payout object corresponds to a single paystub that is available in a user's payroll account.
These are the attributes of the payout object, categorized for convenience:
- Summary information
- Period hours and pay
- YTD hours and pay
- Detailed itemization of gross pay, deductions, taxes, and destinations
- Additional information
- Objects within a payout
Summary information
Basic attributes that provide general details about a payout.
| Attribute | Type | Description |
|---|---|---|
| employer | string | The name of the company that employs the user. |
| employer_address | object See underlying attributes | The employer’s address. |
| status | string | The status of the payout. Possible values are: completed, scheduled, and cancelled. |
| payout_date | string | The payout execution date. Timestamps follow the ISO 8601 standard. |
| payout_period.start_date | string | The start date of the work period for this payout. Timestamps follow the ISO 8601 standard. |
| payout_period.end_date | string | The end date of the work period for this payout. Timestamps follow the ISO 8601 standard. |
| type | string | The method by which the payout was delivered. Possible values are: direct_deposit, paper_check, paypal, money_network, pay_card, and other.See attributes of destinations to obtain further details on how a user's net pay is distributed. |
| currency | string | The currency of the payout—for example, USD or EUR. Currencies follow the ISO 4217 format. |
| filing_status | array of objects See underlying attributes | Contains objects that describe the user’s tax filing status for this payout. |
Period hours and pay
Attributes that contain information about the period hours and pay for a payout.
| Attribute | Type | Description |
|---|---|---|
| hours | string | Total number of hours filed for the payout period. |
| gross_pay | string decimal | The amount earned by the user before any taxes or deductions. |
| net_pay | string decimal | The amount sent to a user after all taxes and deductions. |
| reimbursements | string decimal | Compensation to the user for covering work-related expenses out-of-pocket. |
| deductions | string decimal | The monetary subtractions from the user’s payout. |
| taxes | string decimal | The amount of taxes withheld from the user's gross pay. |
| fees | string decimal | The fee associated with receiving the payout. |
| overtime *deprecated | string decimal | The amount received by the user from working overtime. Deprecated in favor of the gross_pay_list_totals.overtime object. |
| bonuses *deprecated | string decimal | Additional amount added to the base pay. Deprecated in favor of the gross_pay_list_totals.bonus object. |
| commission *deprecated | string decimal | A fee paid to a user for transacting a piece of business, like closing a sale or making a deal. Deprecated in favor of the gross_pay_list_totals.commission object. |
YTD hours and pay
Attributes that contain information about the year-to-date hours and pay for a payout.
Argyle does not calculate these YTD values. These fields return YTD values found on the user’s paystub.
| Attribute | Type | Description |
|---|---|---|
| hours_ytd | string | The total number of hours filed for this calendar year, including this payout’s period. |
| gross_pay_ytd | string decimal | The amount of gross pay earned in this calendar year, including this payout’s period. |
| net_pay_ytd | string decimal | The amount of net pay received in this calendar year, including this payout’s period. |
| deductions_ytd | string decimal | The sum of all deductions subtracted from payouts during this calendar year, including this payout’s period. |
| taxes_ytd | string decimal | The sum of all taxes that have been withheld during this calendar year, including this payout’s period. |
Detailed itemization
Attributes that provide a detailed list of gross pay, deduction, tax line, and destinations items for a payout.
| Attribute | Type | Description |
|---|---|---|
| gross_pay_list | array of objects See underlying attributes | An itemized list of gross pay entries for this payout. Represented as an array of objects, with each object corresponding to one line item. |
| gross_pay_list_totals | array of objects See underlying attributes | Sums of hour and pay values across gross_pay_list objects based on their type. |
| deduction_list | array of objects See underlying attributes | An itemized list of deductions for this payout. Represented as an array of objects, with each object corresponding to one line item. |
| tax_list | array of objects See underlying attributes | An itemized list of tax withholdings for this payout. Represented as an array of objects, with each object corresponding to one line item. |
| destinations | array of objects See underlying attributes | A list of destinations to which the earnings for this payout were sent. Represented as an array of objects, with each object corresponding to one payout destination. |
Additional information
Supplementary attributes that contain additional metadata from a payout and link it to more Argyle data.
| Attribute | Type | Description |
|---|---|---|
| id | string uuid | Unique ID for this payout. |
| document_id | string uuid | Unique ID of the Argyle document object that corresponds to this payout.Use this ID (if available) to retrieve a PDF of this payout as it appears in the user's payroll account, using the following API call: GET /documents/:id. |
| account | string | ID of the account with which this payout is associated.Use this ID to retrieve account details by making the following API call: GET /accounts/:id. |
| metadata | object | Contains any additional information available about this payout. |
| created_at | string timestamp | Time at which the payout object was created. Timestamps follow the ISO 8601 standard. |
| updated_at | string timestamp | Time at which the payout object was last updated. Timestamps follow the ISO 8601 standard. |
Objects within a payout
payoutThis section details the attributes of child objects that can appear within a payout:
employer_addressfiling_statusgross_pay_listgross_pay_list_totalsdeduction_listtax_listdestinations
Attributes of employer_address
employer_addressThe collection of attributes that provide the address details of the user's employer.
| Attribute | Type | Description |
|---|---|---|
| employer_address.line1 | string | Address line 1. For example, street, PO Box, or company name. |
| employer_address.line2 | string | Address line 2. For example, apartment, suite, unit, or building. |
| employer_address.city | string | City, district, suburb, town, or village. |
| employer_address.state | string | State, county, province, or region. |
| employer_address.postal_code | string | ZIP or postal code. |
| employer_address.country | string | Two-letter country code returned in the ISO 3166-1 alpha-2 format. |
Attributes of filing_status
filing_statusThe collection of attributes that provide the user’s tax filing status for this payout.
| Attribute | Type | Description |
|---|---|---|
| filing_status.status | string | The filing status. |
| filing_status.type | string | The type of the filing status. Possible values are: federal, state, and local. |
| filing_status.location | string | The location of the filing status. Depends on filing_status.type:• federal: Returns null.• state: The state name or code; for example "Virginia", "VA".• local: The city name or area code; for example "New Orleans", "395". |
Attributes of gross_pay_list
gross_pay_listgross_pay_list is an array of objects that represents an itemized list of gross pay entries for this payout. Each object corresponds to one line item and contains the following attributes.
| Attribute | Type | Description |
|---|---|---|
| gross_pay_list.name | string | The name of this gross pay item item as shown on the payout—for example, Referral bonus, Sales commission, Overtime FLSA. |
| gross_pay_list.type | string | The type of this gross pay item. This is derived from gross_pay_list.name. Used in gross_pay_list_totals. |
| gross_pay_list.start_date | string | The start date of the work period for this gross pay item. Timestamps follow the ISO 8601 standard. |
| gross_pay_list.end_date | string | The end date of the work period for this gross pay item. Timestamps follow the ISO 8601 standard. |
| gross_pay_list.rate | string decimal | The hourly rate of the users’ earnings for this gross pay item. |
| gross_pay_list.hours | string | The number of hours filed for this gross pay item during the period. |
| gross_pay_list.amount | string decimal | The amount that the user earned for this gross pay item during the period. |
| gross_pay_list.hours_ytd | string | The number of hours filed for this gross pay item in the calendar year including this payout’s period. |
| gross_pay_list.amount_ytd | string decimal | The total amount earned by the user for this gross pay item in the calendar year including this payout’s period. |
Attributes of gross_pay_list_totals
gross_pay_list_totalsgross_pay_list_totals add up the values of gross_pay_list objects based on their type.
| Attribute | Type | Description |
|---|---|---|
| gross_pay_list_totals.base | object See underlying attributes | Adds up hour and pay values across gross_pay_list objects of type = base, fare, holiday, hourly, pto, regular, salary, or vacation. |
| gross_pay_list_totals.overtime | object See underlying attributes | Adds up hour and pay values across gross_pay_list objects of type = overtime or premium. |
| gross_pay_list_totals.commission | object See underlying attributes | Adds up hour and pay values across gross_pay_list objects of type = commission. |
| gross_pay_list_totals.bonus | object See underlying attributes | Adds up hour and pay values across gross_pay_list objects of type = bonus. |
| gross_pay_list_totals.other | object See underlying attributes | Adds up hour and pay values across gross_pay_list objects of all other type values. |
Attributes of gross_pay_list_totals.base
gross_pay_list_totals.base| Attribute | Type | Description |
|---|---|---|
| base.hours | string | Sum of gross_pay_list.hours values. |
| base.amount | string | Sum of gross_pay_list.amount values. |
| base.rate_implied | string | The calculated ratio of gross_pay_list_totals.base.amount and gross_pay_list_totals.base.hours. |
| base.hours_ytd | string | Sum of gross_pay_list.hours_ytd values. |
| base.amount_ytd | string | Sum of gross_pay_list.amount_ytd values. |
| base.rate_implied_ytd | string | The calculated ratio of gross_pay_list_totals.base.amount_ytd and gross_pay_list_totals.base.hours_ytd. |
Attributes of gross_pay_list_totals.overtime
gross_pay_list_totals.overtime| Attribute | Type | Description |
|---|---|---|
| overtime.hours | string | Sum of gross_pay_list.hours values. |
| overtime.amount | string | Sum of gross_pay_list.amount values. |
| overtime.rate_implied | string | The calculated ratio of gross_pay_list_totals.overtime.amount and gross_pay_list_totals.overtime.hours. |
| overtime.hours_ytd | string | Sum of gross_pay_list.hours_ytd values. |
| overtime.amount_ytd | string | Sum of gross_pay_list.amount_ytd values. |
| overtime.rate_implied_ytd | string | The calculated ratio of gross_pay_list_totals.overtime.amount_ytd and gross_pay_list_totals.overtime.hours_ytd. |
Attributes of gross_pay_list_totals.bonus
gross_pay_list_totals.bonus| Attribute | Type | Description |
|---|---|---|
| bonus.hours | string | Sum of gross_pay_list.hours values. |
| bonus.amount | string | Sum of gross_pay_list.amount values. |
| bonus.rate_implied | string | The calculated ratio of gross_pay_list_totals.bonus.amount and gross_pay_list_totals.bonus.hours. |
| bonus.hours_ytd | string | Sum of gross_pay_list.hours_ytd values. |
| bonus.amount_ytd | string | Sum of gross_pay_list.amount_ytd values. |
| bonus.rate_implied_ytd | string | The calculated ratio of gross_pay_list_totals.bonus.amount_ytd and gross_pay_list_totals.bonus.hours_ytd. |
Attributes of gross_pay_list_totals.commission
gross_pay_list_totals.commission| Attribute | Type | Description |
|---|---|---|
| commission.hours | string | Sum of gross_pay_list.hours values. |
| commission.amount | string | Sum of gross_pay_list.amount values. |
| commission.rate_implied | string | The calculated ratio of gross_pay_list_totals.commission.amount and gross_pay_list_totals.commission.hours. |
| commission.hours_ytd | string | Sum of gross_pay_list.hours_ytd values. |
| commission.amount_ytd | string | Sum of gross_pay_list.amount_ytd values. |
| commission.rate_implied_ytd | string | The calculated ratio of gross_pay_list_totals.commission.amount_ytd and gross_pay_list_totals.commission.hours_ytd. |
Attributes of gross_pay_list_totals.other
gross_pay_list_totals.other| Attribute | Type | Description |
|---|---|---|
| other.hours | string | Sum of gross_pay_list.hours values. |
| other.amount | string | Sum of gross_pay_list.amount values. |
| other.rate_implied | string | The calculated ratio of gross_pay_list_totals.other.amount and gross_pay_list_totals.other.hours. |
| other.hours_ytd | string | Sum of gross_pay_list.hours_ytd values. |
| other.amount_ytd | string | Sum of gross_pay_list.amount_ytd values. |
| other.rate_implied_ytd | string | The calculated ratio of gross_pay_list_totals.other.amount and gross_pay_list_totals.other.hours. |
Attributes of deduction_list
deduction_listdeduction_list is an array of objects that represents an itemized list of deductions for this payout. Each object corresponds to one line item, and contains the following attributes.
| Attribute | Type | Description |
|---|---|---|
| deduction_list.name | string | The name of the deduction as shown in the payout—for example, Dental, Vision, Roth. |
| deduction_list.amount | string decimal | The amount of the deduction. |
| deduction_list.amount_ytd | string decimal | The total amount deducted in the calendar year including this payout’s period. |
| deduction_list.tax_classification | string | The tax classification of the deduction. Possible values: pre_tax, and post_tax. |
Attributes of tax_list
tax_listtax_list is an array of objects that represents an itemized list of tax withholdings for this payout. Each object corresponds to one line item, and contains the following attributes.
| Attribute | Type | Description |
|---|---|---|
| tax_list.name | string | The name of the tax, as shown on the payout. A few common examples are Federal Withholding, Social Security Tax, Medicare. |
| tax_list.type | string | The type of the tax. Possible values are: federal, state, local, fica, and other. |
| tax_list.amount | string decimal | The amount of the tax. |
| tax_list.amount_ytd | string decimal | The amount withheld for each individual tax filed in this payout in the calendar year including this payout’s period. |
Attributes of destinations
destinationsThe destinations array of objects details how the user’s net pay is distributed.
| Attribute | Type | Description |
|---|---|---|
| destinations.reference | string | Reference describing the destination. Might include elements of bank name, account number—for example: “Checking - XXXXXXXXXX1234”, “Reserve GoodBank”. |
| destinations.amount | string decimal | The amount of money from this paystub’s net pay that has gone to this destination. |
| destinations.bank_account | object See underlying attributes | Shows details for a bank account used as a destination for this payout. |
| destinations.card | object See underlying attributes | Shows details for a card used as a destination for this payout. |
| destinations.method | string | Name of the method used to deliver funds to the user’s destination—for example: “Direct Deposit”, “Pay Card”. |
| destinations.metadata | string | Metadata holds additional available, often unstructured, information about this destination. |
Attributes of destinations.bank_account
destinations.bank_accountThese attributes contain information about the user’s banks registered on the payroll account.
| Attribute | Type | Description |
|---|---|---|
| bank_account.bank_name | string | Name of the bank for this bank account. |
| bank_account.routing_number | string | 9-digit code that is based on the bank location where the user's account was opened. |
| bank_account.account_number | string | 5 to 17-digit code that identifies the user as the account holder in the bank. In most cases, the account number will be 8-17 digits long. |
Attributes of destinations.card
destinations.cardThese attributes contain information about the user’s associated cards on the payroll account.
| Attribute | Type | Description |
|---|---|---|
| card.name | string | The name of the card that is registered on the payroll account. Note: This attribute does not represent the cardholder's name. |
| card.card_number | string | The card number that is registered on the payroll account. |
Endpoints
These are the endpoints available for payouts.
| Endpoints |
|---|
Retrieve a payout - GET /payouts/:id |
List payouts - GET /payouts |
Sample object
This is a sample of a complete payout object.
{
"id": "018286d8-e69a-7ec5-d291-561ccb5ece34",
"account": "018286d6-7b6b-f79c-4c8c-d30d9177d175",
"document_id": "018286d8-e648-926a-3e55-86be9a33a1a7",
"deduction_list": [
{
"amount": "347.00",
"name": "Med",
"tax_classification": "pre_tax",
"amount_ytd": "347.00"
},
{
"amount": "27.39",
"name": "Vision FT",
"tax_classification": "pre_tax",
"amount_ytd": "27.39"
},
{
"amount": "39.20",
"name": "Dental FT",
"tax_classification": "pre_tax",
"amount_ytd": "39.20"
},
{
"amount": "57.09",
"name": "Future Cntrb",
"tax_classification": "pre_tax",
"amount_ytd": "57.09"
},
{
"amount": "1.00",
"name": "Gnomer Fnd",
"tax_classification": "post_tax",
"amount_ytd": "1.00"
},
{
"amount": "6.88",
"name": "AD&D",
"tax_classification": "post_tax",
"amount_ytd": "6.88"
}
],
"filing_status": [
{
"type": "federal",
"location": null,
"status": "married"
},
{
"type": "state",
"location": null,
"status": "married"
}
],
"tax_list": [
{
"amount": "45.15",
"name": "OASDI",
"type": "fica",
"amount_ytd": "45.15"
},
{
"amount": "10.56",
"name": "Medicare",
"type": "fica",
"amount_ytd": "10.56"
},
{
"amount": "0.58",
"name": "Federal Withholding",
"type": "federal",
"amount_ytd": "0.58"
},
{
"amount": "6.76",
"name": "State Tax - CA",
"type": "state",
"amount_ytd": "6.76"
},
{
"amount": "8.01",
"name": "CA SDI - CASDI",
"type": "state",
"amount_ytd": "8.01"
}
],
"status": "completed",
"type": "direct_deposit",
"payout_date": "2022-01-14T00:00:00Z",
"payout_period": {
"start_date": "2021-12-27T00:00:00Z",
"end_date": "2022-01-09T00:00:00Z"
},
"currency": "USD",
"gross_pay": "1141.84",
"deductions": "478.56",
"taxes": "71.06",
"net_pay": "593.22",
"bonuses": null,
"commission": null,
"overtime": null,
"reimbursements": null,
"hours": "56.00",
"fees": null,
"net_pay_ytd": "593.22",
"gross_pay_ytd": "1141.84",
"metadata": {},
"employer": "GNOME DEPOT U.S.A., INC.",
"employer_address": {
"city": "Atlanta",
"state": "GA",
"country": "US",
"postal_code": "30339",
"line1": "53 First Street",
"line2": null
},
"created_at": "2022-08-10T08:22:18.645Z",
"updated_at": "2022-08-10T08:22:18.645Z",
"destinations": [
{
"reference": null,
"amount": "593.22",
"bank_account": {
"routing_number": null,
"account_number": "******0019",
"bank_name": "FREEDOM BANK"
},
"card": null,
"method": null,
"metadata": null
}
],
"hours_ytd": null,
"deductions_ytd": "478.56",
"taxes_ytd": "71.06",
"gross_pay_list": [
{
"name": "Regular",
"type": "regular",
"start_date": "2021-12-27",
"end_date": "2022-01-02",
"rate": "20.3900",
"hours": "16.0000",
"amount": "326.24",
"hours_ytd": "20.22",
"amount_ytd": null
},
{
"name": "Regular",
"type": "regular",
"start_date": "2022-01-03",
"end_date": "2022-01-09",
"rate": "20.3900",
"hours": "32.0000",
"amount": "652.48",
"hours_ytd": null,
"amount_ytd": "978.72"
},
{
"name": "Holiday Pay",
"type": "holiday",
"start_date": "2021-12-27",
"end_date": "2022-01-09",
"rate": "20.3900",
"hours": "8.0000",
"amount": "163.12",
"hours_ytd": null,
"amount_ytd": "163.12"
},
{
"name": "COVID Expense",
"type": "other",
"start_date": "2021-12-27",
"end_date": "2022-01-09",
"rate": "0.0000",
"hours": "0.0000",
"amount": "1.00",
"hours_ytd": null,
"amount_ytd": "1.00"
}
],
"gross_pay_list_totals": {
"base": {
"amount": "1141.84",
"amount_ytd": "1141.84",
"hours": "56.0000",
"hours_ytd": null,
"rate_implied": "20.3900",
"rate_implied_ytd": null
},
"overtime": null,
"commission": null,
"bonus": null,
"other": {
"amount": "1.00",
"amount_ytd": "1.00",
"hours": "0.0000",
"hours_ytd": null,
"rate_implied": null,
"rate_implied_ytd": null
}
}
}