Payouts

Learn about the /payouts endpoint.

The payout object

payouts 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

Basic attributes that provide general details about a payout.

AttributeTypeDescription
employerstringThe name of the company that employs the user.
employer_addressobject
See underlying attributes
The employer’s address.
statusstringThe status of the payout.

Possible values are: completed, scheduled, and cancelled.
payout_datestringThe payout execution date. Timestamps follow the ISO 8601 standard.
payout_period.start_datestringThe start date of the work period for this payout. Timestamps follow the ISO 8601 standard.
payout_period.end_datestringThe end date of the work period for this payout. Timestamps follow the ISO 8601 standard.
typestringThe 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.
currencystringThe currency of the payout—for example, USD or EUR. Currencies follow the ISO 4217 format.
filing_statusarray 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.

AttributeTypeDescription
hoursstringTotal number of hours filed for the payout period.
gross_paystring decimalThe amount earned by the user before any taxes or deductions.
net_paystring decimalThe amount sent to a user after all taxes and deductions.
reimbursementsstring decimalCompensation to the user for covering work-related expenses out-of-pocket.
deductionsstring decimalThe monetary subtractions from the user’s payout.
taxesstring decimalThe amount of taxes withheld from the user's gross pay.
feesstring decimalThe fee associated with receiving the payout.
overtime
*deprecated
string decimalThe amount received by the user from working overtime.

Deprecated in favor of the gross_pay_list_totals.overtime object.
bonuses
*deprecated
string decimalAdditional amount added to the base pay.

Deprecated in favor of the gross_pay_list_totals.bonus object.
commission
*deprecated
string decimalA 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.

AttributeTypeDescription
hours_ytdstringThe total number of hours filed for this calendar year, including this payout’s period.
gross_pay_ytdstring decimalThe amount of gross pay earned in this calendar year, including this payout’s period.
net_pay_ytdstring decimalThe amount of net pay received in this calendar year, including this payout’s period.
deductions_ytdstring decimalThe sum of all deductions subtracted from payouts during this calendar year, including this payout’s period.
taxes_ytdstring decimalThe 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.

AttributeTypeDescription
gross_pay_listarray 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_totalsarray of objects
See underlying attributes
Sums of hour and pay values across gross_pay_list objects based on their type.
deduction_listarray 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_listarray 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.
destinationsarray 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.

AttributeTypeDescription
idstring uuidUnique ID for this payout.
document_idstring uuidUnique 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.
accountstringID 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.
metadataobjectContains any additional information available about this payout.
created_atstring
timestamp
Time at which the payout object was created. Timestamps follow the ISO 8601 standard.
updated_atstring
timestamp
Time at which the payout object was last updated. Timestamps follow the ISO 8601 standard.

Objects within a payout

This section details the attributes of child objects that can appear within a payout:

Attributes of employer_address

The collection of attributes that provide the address details of the user's employer.

AttributeTypeDescription
employer_address.line1stringAddress line 1. For example, street, PO Box, or company name.
employer_address.line2stringAddress line 2. For example, apartment, suite, unit, or building.
employer_address.citystringCity, district, suburb, town, or village.
employer_address.statestringState, county, province, or region.
employer_address.postal_codestringZIP or postal code.
employer_address.countrystringTwo-letter country code returned in the ISO 3166-1 alpha-2 format.

Attributes of filing_status

The collection of attributes that provide the user’s tax filing status for this payout.

AttributeTypeDescription
filing_status.statusstringThe filing status.
filing_status.typestringThe type of the filing status.
Possible values are: federal, state, and local.
filing_status.locationstringThe 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 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.

AttributeTypeDescription
gross_pay_list.namestringThe name of this gross pay item item as shown on the payout—for example, Referral bonus, Sales commission, Overtime FLSA.
gross_pay_list.typestringThe type of this gross pay item. This is derived from gross_pay_list.name. Used in gross_pay_list_totals.
gross_pay_list.start_datestringThe start date of the work period for this gross pay item. Timestamps follow the ISO 8601 standard.
gross_pay_list.end_datestringThe end date of the work period for this gross pay item. Timestamps follow the ISO 8601 standard.
gross_pay_list.ratestring decimalThe hourly rate of the users’ earnings for this gross pay item.
gross_pay_list.hoursstringThe number of hours filed for this gross pay item during the period.
gross_pay_list.amountstring decimalThe amount that the user earned for this gross pay item during the period.
gross_pay_list.hours_ytdstringThe number of hours filed for this gross pay item in the calendar year including this payout’s period.
gross_pay_list.amount_ytdstring decimalThe 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 add up the values of gross_pay_list objects based on their type.

AttributeTypeDescription
gross_pay_list_totals.baseobject
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.overtimeobject
See underlying attributes
Adds up hour and pay values across gross_pay_list objects of type = overtime or premium.
gross_pay_list_totals.commissionobject
See underlying attributes
Adds up hour and pay values across gross_pay_list objects of type = commission.
gross_pay_list_totals.bonusobject
See underlying attributes
Adds up hour and pay values across gross_pay_list objects of type = bonus.
gross_pay_list_totals.otherobject
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

AttributeTypeDescription
base.hoursstringSum of gross_pay_list.hours values.
base.amountstringSum of gross_pay_list.amount values.
base.rate_impliedstringThe calculated ratio of gross_pay_list_totals.base.amount and gross_pay_list_totals.base.hours.
base.hours_ytdstringSum of gross_pay_list.hours_ytd values.
base.amount_ytdstringSum of gross_pay_list.amount_ytd values.
base.rate_implied_ytdstringThe 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

AttributeTypeDescription
overtime.hoursstringSum of gross_pay_list.hours values.
overtime.amountstringSum of gross_pay_list.amount values.
overtime.rate_impliedstringThe calculated ratio of gross_pay_list_totals.overtime.amount and gross_pay_list_totals.overtime.hours.
overtime.hours_ytdstringSum of gross_pay_list.hours_ytd values.
overtime.amount_ytdstringSum of gross_pay_list.amount_ytd values.
overtime.rate_implied_ytdstringThe 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

AttributeTypeDescription
bonus.hoursstringSum of gross_pay_list.hours values.
bonus.amountstringSum of gross_pay_list.amount values.
bonus.rate_impliedstringThe calculated ratio of gross_pay_list_totals.bonus.amount and gross_pay_list_totals.bonus.hours.
bonus.hours_ytdstringSum of gross_pay_list.hours_ytd values.
bonus.amount_ytdstringSum of gross_pay_list.amount_ytd values.
bonus.rate_implied_ytdstringThe 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

AttributeTypeDescription
commission.hoursstringSum of gross_pay_list.hours values.
commission.amountstringSum of gross_pay_list.amount values.
commission.rate_impliedstringThe calculated ratio of gross_pay_list_totals.commission.amount and gross_pay_list_totals.commission.hours.
commission.hours_ytdstringSum of gross_pay_list.hours_ytd values.
commission.amount_ytdstringSum of gross_pay_list.amount_ytd values.
commission.rate_implied_ytdstringThe 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

AttributeTypeDescription
other.hoursstringSum of gross_pay_list.hours values.
other.amountstringSum of gross_pay_list.amount values.
other.rate_impliedstringThe calculated ratio of gross_pay_list_totals.other.amount and gross_pay_list_totals.other.hours.
other.hours_ytdstringSum of gross_pay_list.hours_ytd values.
other.amount_ytdstringSum of gross_pay_list.amount_ytd values.
other.rate_implied_ytdstringThe calculated ratio of gross_pay_list_totals.other.amount and gross_pay_list_totals.other.hours.

Attributes of 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.

AttributeTypeDescription
deduction_list.namestringThe name of the deduction as shown in the payout—for example, Dental, Vision, Roth.
deduction_list.amountstring decimalThe amount of the deduction.
deduction_list.amount_ytdstring decimalThe total amount deducted in the calendar year including this payout’s period.
deduction_list.tax_classificationstringThe tax classification of the deduction.
Possible values: pre_tax, and post_tax.

Attributes of 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.

AttributeTypeDescription
tax_list.namestringThe name of the tax as shown in the payout—for example, Federal Withholding, Social Security Tax, Medicare.
tax_list.typestringThe type of the tax.
Possible values are: federal, state, local, fica, and other.
tax_list.amountstring decimalThe amount of the tax.
tax_list.amount_ytdstring decimalThe amount withheld for each individual tax filed in this payout in the calendar year including this payout’s period.

Attributes of destinations

The destinations array of objects details how the user’s net pay is distributed.

AttributeTypeDescription
destinations.referencestringReference describing the destination. Might include elements of bank name, account number—for example: “Checking - XXXXXXXXXX1234”, “Reserve GoodBank”.
destinations.amountstring decimalThe amount of money from this paystub’s net pay that has gone to this destination.
destinations.bank_accountobject
See underlying attributes
Shows details for a bank account used as a destination for this payout.
destinations.cardobject
See underlying attributes
Shows details for a card used as a destination for this payout.
destinations.methodstringName of the method used to deliver funds to the user’s destination—for example: “Direct Deposit”, “Pay Card”.
destinations.metadatastringMetadata holds additional available, often unstructured, information about this destination.

Attributes of destinations.bank_account

These attributes contain information about the user’s banks registered on the payroll account.

AttributeTypeDescription
bank_account.bank_namestringName of the bank for this bank account.
bank_account.routing_numberstring9-digit code that is based on the bank location where the user's account was opened.
bank_account.account_numberstring5 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

These attributes contain information about the user’s associated cards on the payroll account.

AttributeTypeDescription
card.namestringThe name of the card that is registered on the payroll account.

Note: This attribute does not represent the cardholder's name.
card.card_numberstringThe 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
        }
    }
}