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
payout
This section details the attributes of child objects that can appear within a payout
:
employer_address
filing_status
gross_pay_list
gross_pay_list_totals
deduction_list
tax_list
destinations
Attributes of employer_address
employer_address
The 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_status
The 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_list
gross_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_totals
gross_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_list
deduction_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_list
tax_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
destinations
The 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_account
These 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.card
These 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
}
}
}