Deel: List payroll groups for a legal entity
Deel globalPayroll.listPayrollGroups: arguments, response, policy and SDK examples.
← Global payroll operations · Get started
Operation deel.globalpayroll_listpayrollgroups_v2026_09_08
Provider route: GET /payroll-groups. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/deel with npm, or alter-sdk-deel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { DeelIntegration } from "@alter-ai/deel";
async function execute(input: Parameters<DeelIntegration["globalPayroll"]["listPayrollGroups"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new DeelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.globalPayroll.listPayrollGroups(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_deel import DeelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = DeelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.global_payroll.list_payroll_groups(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
query | object | Required within parent | Additional keys: not allowed |
query.legalEntityId | string | Required within parent | Format: uuid |
query.calendarYear | integer | Optional | Maximum: 2035 Minimum: 2020 |
query.includePayrollCalendar | boolean | Optional | Default: true |
query.pagination | Model | Optional | Expand List payroll groups for a legal entity — request body — query pagination Default: {“limit”: 10} |
Referenced models: List payroll groups for a legal entity — request body — query pagination
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand List payroll groups for a legal entity — 200 response body |
Referenced models: List payroll groups for a legal entity — 200 response body
Schemas
Section titled “Schemas”List payroll groups for a legal entity — 200 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
data | array | Required within parent | |
data[] | Model | Each item | Expand List payroll groups for a legal entity — 200 response body — data item |
pagination | Model | Required within parent | Expand List payroll groups for a legal entity — 200 response body — pagination |
Referenced models: List payroll groups for a legal entity — 200 response body — data item, List payroll groups for a legal entity — 200 response body — pagination
List payroll groups for a legal entity — request body — query pagination
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
cursor | string | Optional | Maximum length: 256 Minimum length: 1 Pattern: ^[A-Za-z0-9_-]+$ |
limit | integer | Optional | Default: 10 Maximum: 15 Minimum: 1 |
List payroll groups for a legal entity — 200 response body — data item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
calendars | array | Required within parent | REGULAR calendars for this group within the requested year. |
calendars[] | Model | Each item | Expand List payroll groups for a legal entity — 200 response body — data item calendars item |
id | string | Required within parent | Unique identifier of the payroll group. |
is_active | boolean | Required within parent | Whether the payroll group is currently active. |
name | string | Required within parent | Human-readable name of the payroll group. |
regular_cycle_cadence | string | Required within parent | Frequency at which regular payroll cycles are run for this group. Known values: WEEKLY, BIWEEKLY, MONTHLY, BIMONTHLY, FOUR_WEEKLY, QUARTERLY |
Referenced models: List payroll groups for a legal entity — 200 response body — data item calendars item
List payroll groups for a legal entity — 200 response body — pagination
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
hasMore | boolean | Required within parent | Whether additional pages exist after this one. |
limit | JSON | Required within parent | |
limit (anyOf 1) | integer | Alternative | Maximum number of items returned in this page. Maximum: 9007199254740991 Minimum: 1 |
limit (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
nextCursor | JSON | Required within parent | |
nextCursor (anyOf 1) | string | Alternative | Opaque cursor for the next page, or null when there are no more results. |
nextCursor (anyOf 2) | null | Alternative | Opaque cursor for the next page, or null when there are no more results. |
List payroll groups for a legal entity — 200 response body — data item calendars item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
calendar_type | string | Required within parent | Type of the calendar, e.g. REGULAR. |
id | string | Required within parent | Unique identifier of the calendar. |
values | object | Required within parent | Map of calendar milestone keys to their scheduled date-time values. A calendar holds only the milestones its payroll uses. Possible keys: - `START`: Start date of the payroll cycle. - `END`: End date of the payroll cycle. - `CYCLE_SUBMISSION`: Deadline to submit payroll inputs for the cycle. - `CYCLE_PUBLISHING`: Date the processed payroll is published for review. - `CYCLE_APPROVAL`: Deadline to approve the payroll (for EOR, the payments package). - `PAYROLL_FUNDING`: Date the payroll funding invoice is issued. - `FUNDING_PAYMENT_RECEIPT`: Date the funding payment must be received. - `INVOICE_PUBLISHING`: Date the payroll invoices are published. - `PAYMENT_RELEASE`: Date the salary payments are released. - `PAYSLIPS_PUBLISHING`: Date the payslips are published. - `SALARY_PAY`: Date the employees are paid. - `TIME_SHEETS_CUT_OFF`: Cut-off date for timesheets to be included in the cycle. - `LATE_STARTERS_CUTOFF`: Cut-off date for new hires to be included in the cycle. - `SOFT_G2N_UPLOAD`: Date the gross-to-net (G2N) report is uploaded. - `FINAL_BATCH_REPORTS`: Date the final batch reports are delivered. Additional keys: see wildcard field |
values.* | Model | Additional keys | Expand List payroll groups for a legal entity — 200 response body — data item calendars item values value |
Referenced models: List payroll groups for a legal entity — 200 response body — data item calendars item values value
List payroll groups for a legal entity — 200 response body — data item calendars item values value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
value | string | Required within parent | ISO-8601 date-time value for this calendar key. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: deel.globalpayroll_listpayrollgroups_v2026_09_08. Catalog operation: globalpayroll_listpayrollgroups_v2026_09_08. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["global-payroll:read"]
Pinned headers: {"X-Version": "2026-09-08"}