Get Pay Groups

Get Pay Groups

Use this endpoint to list all pay groups configured for the employer. Results can be filtered by employee or pay frequency. Copy the id values from the response — these are the pay_group_id values needed by GET /payroll/pay-groups/{pay_group_id}.

GET payroll/pay-groups 

Header Parameters

Field	Type	Description
Authorization	string	Required. Bearer token obtained from the Auth endpoint. Format: Bearer <access_token>.
X-TaxBandits-Version	string	API version string. Use 1.0.0.

Query Parameters

Field	Type	Description
entity_ids	string	Required. The organization ID. Must be exactly one UUID.
individual_id	string	Optional Filter to pay groups that include this employee (UUID).
pay_frequencies	string[]	Optional Filter by pay frequency. Supported values: annually, semi_annually, quarterly, monthly, semi_monthly, bi_weekly, weekly, daily, other.

Response Body

Field	Type	Description
status	string	SUCCESS or FAILURE.
status_code	number	HTTP status code (e.g. 200).
message	string	Human-readable status message.
response	object[]	List of pay groups.
id	string	The pay group UUID (pay_group_id).
name	string	Name of the pay group.
pay_frequencies	string[]	Pay frequencies for this group (e.g. ["bi_weekly"]).

Payload

Request

GET payroll/pay-groups?entity_ids=519a84f4-...&pay_frequencies=bi_weekly
Header: X-TaxBandits-Version: 1.0.0

Response Json

Sample	Description	Action
200	Success Response - This is a sample response for successful API requests.
400	Bad Request Response - You'll get the below response when entity_ids is missing or invalid.

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": [
    {
      "id": "a1b2c3d4-1111-2222-3333-444455556666",
      "name": "Bi-Weekly Group",
      "pay_frequencies": [
        "bi_weekly"
      ]
    }
  ]
}