Payouts

Learn about the /payouts endpoint, including available attributes and methods.

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.

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.

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.

Has been superseded by the gross_pay_list_totals.overtime object.

bonuses - *deprecated

string decimal

Additional amount added to the base pay.

Has been superseded by 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.

Has been superseded by 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.

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.

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.

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

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

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_ytd_impliedstringThe 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_ytd_impliedstringThe 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_ytd_impliedstringThe 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_ytd_impliedstringThe 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_ytd_impliedstringThe 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.

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 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 in the payout—for example, 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

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

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

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 platform.

Attribute

Type

Description

card.name

string

The name of the card that is registered on the platform.

Note: This attribute does not represent the cardholder's name.

card.card_number

string

The card number that is registered on the platform.

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": null,
    "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": null,
            "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
        }
    }
}