Pay Statement

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

// Automatically fetches more pages as needed.
for await (const payStatementResponse of client.hris.payStatements.retrieveMany({
  requests: [{ payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],
})) {
  console.log(payStatementResponse.payment_id);
}

{
  "responses": [
    {
      "payment_id": "fc8b024e-d373-4c9c-80fc-f1625383d142",
      "code": 200,
      "body": {
        "paging": {
          "count": 25,
          "offset": 10
        },
        "pay_statements": [
          {
            "individual_id": "be7b048c-a6f3-4194-a017-2f537d4f3565",
            "type": "regular_payroll",
            "payment_method": "check",
            "total_hours": 42.5,
            "gross_pay": {
              "amount": 230000,
              "currency": "usd"
            },
            "net_pay": {
              "amount": 180000,
              "currency": "usd"
            },
            "earnings": [
              {
                "type": "salary",
                "name": "Salary",
                "amount": 230000,
                "currency": "usd",
                "hours": 42.5
              }
            ],
            "taxes": [
              {
                "type": "state",
                "name": "State Withholding - OR",
                "employer": false,
                "amount": 0,
                "currency": "usd"
              }
            ],
            "employee_deductions": [
              {
                "name": "Pre-Tax 401k",
                "amount": 50000,
                "currency": "usd",
                "pre_tax": true,
                "type": "401k"
              }
            ],
            "employer_contributions": [
              {
                "name": "Employee Medical Insurance",
                "amount": 23272,
                "currency": "usd",
                "type": "s125_medical"
              }
            ]
          }
        ]
      }
    }
  ]
}

POST

employer

pay-statement

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

// Automatically fetches more pages as needed.
for await (const payStatementResponse of client.hris.payStatements.retrieveMany({
  requests: [{ payment_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' }],
})) {
  console.log(payStatementResponse.payment_id);
}

{
  "responses": [
    {
      "payment_id": "fc8b024e-d373-4c9c-80fc-f1625383d142",
      "code": 200,
      "body": {
        "paging": {
          "count": 25,
          "offset": 10
        },
        "pay_statements": [
          {
            "individual_id": "be7b048c-a6f3-4194-a017-2f537d4f3565",
            "type": "regular_payroll",
            "payment_method": "check",
            "total_hours": 42.5,
            "gross_pay": {
              "amount": 230000,
              "currency": "usd"
            },
            "net_pay": {
              "amount": 180000,
              "currency": "usd"
            },
            "earnings": [
              {
                "type": "salary",
                "name": "Salary",
                "amount": 230000,
                "currency": "usd",
                "hours": 42.5
              }
            ],
            "taxes": [
              {
                "type": "state",
                "name": "State Withholding - OR",
                "employer": false,
                "amount": 0,
                "currency": "usd"
              }
            ],
            "employee_deductions": [
              {
                "name": "Pre-Tax 401k",
                "amount": 50000,
                "currency": "usd",
                "pre_tax": true,
                "type": "401k"
              }
            ],
            "employer_contributions": [
              {
                "name": "Employee Medical Insurance",
                "amount": 23272,
                "currency": "usd",
                "type": "s125_medical"
              }
            ]
          }
        ]
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Please use your Access Token

Headers

Finch-API-Version

string<date>

default:2020-09-17

required

Header used to specify the version for a given API request. Current version is 2020-09-17.

Content-Type

string

default:application/json

required

Used to indicate the original media type of the resource

Query Parameters

entity_ids

string<uuid>[]

The entity IDs to specify which entities' data to access.

Required array length: 1 element

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Body

application/json

requests

object[]

required

The array of batch requests.

Show child attributes

requests.payment_id

string<uuid>

required

A stable Finch id (UUID v4) for a payment.

requests.limit

integer

Number of pay statements to return (defaults to all).

Example:

50

requests.offset

integer

Index to start from.

Example:

0

Response

Pay statement data

responses

object[]

required

Show child attributes

responses.payment_id

string

required

responses.code

integer

required

responses.body

object

required

Option 1
Option 2
Option 3

Show child attributes

responses.body.paging

Paging · object

required

Show child attributes

responses.body.paging.offset

integer

required

The current start index of the returned list of elements

responses.body.paging.count

integer

The total number of elements for the entire query (not just the given page)

responses.body.pay_statements

Pay Statement · object[]

required

Show child attributes

responses.body.pay_statements.individual_id

string

required

A stable Finch id (UUID v4) for an individual in the company

responses.body.pay_statements.type

enum<string> | null

required

The type of the payment associated with the pay statement.

Available options:

off_cycle_payroll,

one_time_payment,

regular_payroll,

responses.body.pay_statements.payment_method

enum<string> | null

required

The payment method.

Available options:

check,

direct_deposit,

other,

responses.body.pay_statements.total_hours

number | null

required

The number of hours worked for this pay period

responses.body.pay_statements.gross_pay

Money · object

required

Show child attributes

responses.body.pay_statements.gross_pay.amount

integer | null

required

Amount for money object (in cents)

responses.body.pay_statements.gross_pay.currency

string

required

responses.body.pay_statements.net_pay

Money · object

required

Show child attributes

responses.body.pay_statements.net_pay.amount

integer | null

required

Amount for money object (in cents)

responses.body.pay_statements.net_pay.currency

string

required

responses.body.pay_statements.earnings

(object | null)[] | null

required

The array of earnings objects associated with this pay statement

Show child attributes

responses.body.pay_statements.earnings.type

enum<string> | null

required

The type of earning.

Available options:

salary,

wage,

reimbursement,

overtime,

severance,

double_overtime,

pto,

sick,

bonus,

commission,

tips,

1099,

other,

responses.body.pay_statements.earnings.name

string | null

required

The exact name of the deduction from the pay statement.

responses.body.pay_statements.earnings.amount

integer | null

required

The earnings amount in cents.

responses.body.pay_statements.earnings.currency

string | null

required

The earnings currency code.

responses.body.pay_statements.earnings.hours

number | null

required

The number of hours associated with this earning. (For salaried employees, this could be hours per pay period, 0 or null, depending on the provider).

responses.body.pay_statements.earnings.attributes

object

Show child attributes

responses.body.pay_statements.earnings.attributes.metadata

object

required

The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).

Show child attributes

responses.body.pay_statements.earnings.attributes.metadata.{key}

object

responses.body.pay_statements.taxes

object[] | null

required

The array of taxes objects associated with this pay statement.

Show child attributes

responses.body.pay_statements.taxes.type

enum<string> | null

required

The type of taxes.

Available options:

state,

federal,

local,

fica,

responses.body.pay_statements.taxes.name

string | null

required

The exact name of tax from the pay statement.

responses.body.pay_statements.taxes.employer

boolean | null

required

true if the amount is paid by the employers.

responses.body.pay_statements.taxes.currency

string | null

required

The currency code.

responses.body.pay_statements.taxes.amount

integer | null

The tax amount in cents.

responses.body.pay_statements.taxes.attributes

object

Show child attributes

responses.body.pay_statements.taxes.attributes.metadata

object

required

The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).

Show child attributes

responses.body.pay_statements.taxes.attributes.metadata.{key}

object

responses.body.pay_statements.employee_deductions

object[] | null

required

The array of deductions objects associated with this pay statement.

Show child attributes

responses.body.pay_statements.employee_deductions.name

string | null

required

The deduction name from the pay statement.

responses.body.pay_statements.employee_deductions.amount

integer | null

required

The deduction amount in cents.

responses.body.pay_statements.employee_deductions.currency

string | null

required

The deduction currency.

responses.body.pay_statements.employee_deductions.pre_tax

boolean | null

required

Boolean indicating if the deduction is pre-tax.

responses.body.pay_statements.employee_deductions.type

enum<string> | null

required

Type of benefit.

Available options:

457,

401k,

401k_roth,

401k_loan,

403b,

403b_roth,

457_roth,

commuter,

custom_post_tax,

custom_pre_tax,

fsa_dependent_care,

fsa_medical,

hsa_post,

hsa_pre,

s125_dental,

s125_medical,

s125_vision,

simple,

simple_ira,

responses.body.pay_statements.employee_deductions.attributes

object

Show child attributes

responses.body.pay_statements.employee_deductions.attributes.metadata

object

required

The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).

Show child attributes

responses.body.pay_statements.employee_deductions.attributes.metadata.{key}

object

responses.body.pay_statements.employer_contributions

object[] | null

required

Show child attributes

responses.body.pay_statements.employer_contributions.name

string | null

required

The contribution name from the pay statement.

responses.body.pay_statements.employer_contributions.currency

string | null

required

The contribution currency.

responses.body.pay_statements.employer_contributions.type

enum<string> | null

required

Type of benefit.

Available options:

457,

401k,

401k_roth,

401k_loan,

403b,

403b_roth,

457_roth,

commuter,

custom_post_tax,

custom_pre_tax,

fsa_dependent_care,

fsa_medical,

hsa_post,

hsa_pre,

s125_dental,

s125_medical,

s125_vision,

simple,

simple_ira,

responses.body.pay_statements.employer_contributions.amount

integer | null

The contribution amount in cents.

responses.body.pay_statements.employer_contributions.attributes

object

Show child attributes

responses.body.pay_statements.employer_contributions.attributes.metadata

object

required

The metadata to be attached to the entity by existing rules. It is a key-value pairs where the values can be of any type (string, number, boolean, object, array, etc.).

Show child attributes

responses.body.pay_statements.employer_contributions.attributes.metadata.{key}

object

Payment Get All Pay Groups

⌘I

Organization

Payroll

Deductions

Documents

Connect

Management

Sandbox

Development Guides

Pay Statement

Authorizations

Headers

Query Parameters

Body

Response