--- title: "Create a contractor payment group" method: POST path: "/v1/companies/{company_id}/contractor_payment_groups" tags: ["Contractor Payment Groups"] --- # Create a contractor payment group `POST /v1/companies/{company_id}/contractor_payment_groups` ## Request - Base URL: `https://api.gusto-demo.com` - URL: `https://api.gusto-demo.com/v1/companies/{company_id}/contractor_payment_groups` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Pay a group of contractors. Information needed depends on the contractor's wage type (hourly vs fixed) scope: `payrolls:run` ## Path parameters - `company_id` string, required ## Headers - `X-Gusto-API-Version` '2026-06-15' ## Request body - object - `check_date` string, date, required: The payment check date - `creation_token` string, required: A token used to make contractor payment group creation idempotent. The string must be unique for each group you intend to create. - `submission_blockers` object[]: Optional array of submission blockers with selected unblock options. Returned from the preview endpoint and can be submitted with selected_option to resolve blockers. - `blocker_type` string: The type of blocker that is blocking the payment submission - `selected_option` string, nullable: The unblock option selected to resolve the submission blocker - `message` string: Optional message related to the blocker - `options` object[]: Optional array of additional options for the blocker - `type` string: The type of option - `message` string: Message for the option - `contractor_payments` object[], required - `contractor_uuid` string: The contractor receiving the payment - `payment_method` 'Direct Deposit' | 'Check' | 'Historical Payment' - `wage` string, float: If the contractor is on a fixed wage, this is the fixed wage payment for the contractor, regardless of hours worked - `hours` string, float: If the contractor is on an hourly wage, this is the number of hours that the contractor worked for the payment - `bonus` string, float: If the contractor is on an hourly wage, this is the bonus the contractor earned - `reimbursement` string, float: Reimbursed wages for the contractor - `invoice_number` string: An optional invoice number to associate with this contractor payment. This will be visible to the contractor on their paystub. - `memo` string: An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub. ## Response `201` Full contractor payment group object - ContractorPaymentGroup: Base properties for contractor payment groups. - `uuid` string: The unique identifier of the contractor payment group. - `company_uuid` string: The UUID of the company. - `check_date` string: The check date of the contractor payment group. - `debit_date` string: 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_token` string, nullable: Token used to make contractor payment group creation idempotent. Will error if attempting to create a group with a duplicate token. - `partner_owned_disbursement` boolean, nullable: Whether the disbursement is partner owned. - `submission_blockers` PayrollSubmissionBlockerType[]: List of submission blockers for the contractor payment group. - `blocker_type` string: The type of blocker that's blocking the payment submission. - `blocker_name` string: The name of the submission blocker. - `unblock_options` object[]: The available options to unblock a submission blocker. - `unblock_type` string: The type of unblock option for the submission blocker. - `check_date` string: The payment check date associated with the unblock option. - `metadata` object: Additional data associated with the unblock option. - `selected_option` string, nullable: The unblock option that's been selected to resolve the submission blocker. - `status` 'unresolved' | 'resolved': The status of the submission blocker. - `credit_blockers` PayrollCreditBlockerType[]: List of credit blockers for the contractor payment group. - `blocker_type` string: The type of blocker that's blocking the payment from being credited. - `blocker_name` string: The name of the credit blocker. - `unblock_options` union[]: The available options to unblock a credit blocker. - union - PayrollCreditBlockerUnblockOptionSubmitWire: Unblock option to resolve a credit blocker by submitting a wire transfer - `unblock_type` 'submit_wire', required: The type of unblock option for the credit blocker - `check_date` string, required: The payment check date associated with the unblock option - `metadata` object, required - `wire_in_amount` string, required: The amount to be wired in (decimal string) - `wire_in_deadline` string, date-time, required: Deadline for the wire transfer to be received - `wire_in_request_uuid` string, required: UUID of the wire in request - PayrollCreditBlockerUnblockOptionSubmitBankScreenshot: Unblock option to resolve a credit blocker by submitting a bank screenshot - `unblock_type` 'submit_bank_screenshot', required: The type of unblock option for the credit blocker - `check_date` string, required: The payment check date associated with the unblock option - `metadata` object, required - `information_request_uuid` string, required: UUID of the information request - `bank_account_last_four_digits` string, nullable: Last 4 digits of the bank account number for the bank screenshot RFI - PayrollCreditBlockerUnblockOptionRespondToHighRiskFraudRfi: Unblock option to resolve a credit blocker by responding to high risk fraud RFI - `unblock_type` 'respond_to_high_risk_fraud_rfi', required: The type of unblock option for the credit blocker - `check_date` string, required: The payment check date associated with the unblock option - `metadata` object, required - `information_request_uuid` string, required: UUID of the information request - PayrollCreditBlockerUnblockOptionWaitForReverseWire: Unblock option to resolve a credit blocker by waiting for reverse wire - `unblock_type` 'wait_for_reverse_wire', required: The type of unblock option for the credit blocker - `check_date` string, required: The payment check date associated with the unblock option - `metadata` object, required - `selected_option` string, nullable: The unblock option that's been selected to resolve the credit blocker. - `status` 'unresolved' | 'pending_review' | 'resolved' | 'failed': The status of the credit blocker - `totals` object - `amount` string: The total amount for the group of contractor payments. - `debit_amount` string: The total debit amount for the group of contractor payments. Sum of wage & reimbursement amount. - `wage_amount` string: The total wage amount for the group of contractor payments. - `reimbursement_amount` string: The total reimbursement amount for the group of contractor payments. - `check_amount` string: The total check amount for the group of contractor payments. - `contractor_payments` ContractorPaymentForGroup[] - `uuid` string: The unique identifier of the contractor payment in Gusto. - `contractor_uuid` string: The UUID of the contractor. - `bonus` string: The bonus amount in the payment. - `hours` string: The number of hours worked for the payment. - `payment_method` 'Direct Deposit' | 'Check' | 'Historical Payment' | 'Correction Payment': The payment method. - `reimbursement` string: The reimbursement amount in the payment. - `status` 'Funded' | 'Unfunded': The status of the contractor payment. Will transition to `Funded` during payments processing if the payment should be funded, i.e. has `Direct Deposit` for payment method. Contractors payments with `Check` payment method will remain `Unfunded`. - `hourly_rate` string: The rate per hour worked for the payment. - `may_cancel` boolean: Determine if the contractor payment can be cancelled. - `wage` string: The fixed wage of the payment, regardless of hours worked. - `wage_type` 'Hourly' | 'Fixed': The wage type for the payment. - `wage_total` string: (hours * hourly_rate) + wage + bonus - `invoice_number` string, nullable: An optional invoice number associated with this contractor payment. This will be visible to the contractor on their paystub. Maximum 25 characters. - `memo` string, nullable: An optional note or memo for this contractor payment. This will be visible to the contractor on their paystub. ## Other responses - `404`: Not Found The requested company does not exist. Make sure the provided UUID is valid. - `422`: Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details. --- [API](https://skmtc.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)