Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Contractor Payment Groups

Preview a contractor payment group

Preview a group of contractor payments. Request will validate inputs and return preview of the contractor payment group including the expected debit_date. The uuid field will be null in the response.

The returned creation_token is a required parameter in order to create the contractor payment group.

scope: payrolls:read

post/v1/companies/{company_id}/contractor_payment_groups/preview

Path parameters

company_idstring required

The UUID of the company

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Request body

check_datestring date

Date when payments should be processed

Example request

{
  "contractor_payments": [
    {
      "wage": "5000.0",
      "hours": "40.0",
      "bonus": "500.0",
      "reimbursement": "20.0",
      "invoice_number": "INV-001",
      "memo": "Payment for consulting services"
    }
  ]
}

Response

Full contractor payment group object with null uuid

uuidstring nullable

The unique identifier of the contractor payment group.

company_uuidstring

The UUID of the company.

check_datestring

The check date of the contractor payment group.

debit_datestring

The debit date of the contractor payment group.

status'Unfunded' | 'Funded'

The status of the contractor payment group. Will be Funded if all payments that should be funded (i.e. have Direct Deposit for payment method) are funded. A group can have status Funded while having associated payments that have status Unfunded, i.e. payment with Check payment method.

creation_tokenstring nullable

Token used to make contractor payment group creation idempotent. Will error if attempting to create a group with a duplicate token.

partner_owned_disbursementboolean nullable

Whether the disbursement is partner owned.