Payroll

Everything about pay, and nothing writable. The figure on an entry is the product of attendance, leave, loans, bonuses, adjustments, statutory contributions and tax slabs — a write path that set it directly would produce a number the workspace itself disagrees with.

Money is a decimal string at two places; days are at one, because half days are real and hundredths of a day are not.

Plan feature

These endpoints need a plan that includes Payroll (payroll). On a plan without it, requests return 402 with code: plan_upgrade_required and feature naming what an upgrade would add.

List salary components

GET/v1/salary_components

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
is_active	boolean	No	Filter by whether the record is in use.
type	string	No	earning, deduction, or employer_contribution.
code	string	No	Look up one component by its code.

Responses

Status	Meaning
200	A page of salary components.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a salary component

GET/v1/salary_components/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The salary component.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such salary component in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List salary structures

GET/v1/salary_structures

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
is_active	boolean	No	Filter by whether the record is in use.

Responses

Status	Meaning
200	A page of salary structures.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a salary structure

GET/v1/salary_structures/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The salary structure.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such salary structure in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List salary structure components

GET/v1/salary_structure_components

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
salary_structure_id	string	No	Only components of this structure.
salary_component_id	string	No	Only rows for this component.

Responses

Status	Meaning
200	A page of salary structure components.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a salary structure component

GET/v1/salary_structure_components/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The salary structure component.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such salary structure component in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List salary assignments

GET/v1/salary_assignments

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
employee_id	string	No	Only records for this employee.
salary_structure_id	string	No	Only assignments on this structure.

Responses

Status	Meaning
200	A page of salary assignments.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a salary assignment

GET/v1/salary_assignments/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The salary assignment.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such salary assignment in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List payroll runs

GET/v1/payroll_runs

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
status	string	No	Only runs in this state.
source	string	No	processed or imported.
month	integer	No	Calendar month, 1–12.
year	integer	No	Calendar year.

Responses

Status	Meaning
200	A page of payroll runs.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a payroll run

GET/v1/payroll_runs/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The payroll run.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such payroll run in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List payroll entries

GET/v1/payroll_entries

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
employee_id	string	No	Only records for this employee.
payroll_run_id	string	No	Only entries in this run.
status	string	No	Only entries in this state.

Responses

Status	Meaning
200	A page of payroll entries.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a payroll entry

GET/v1/payroll_entries/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The payroll entry.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such payroll entry in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List payroll entry components

GET/v1/payroll_entry_components

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
payroll_entry_id	string	No	Only lines on this entry.
salary_component_id	string	No	Only lines for this component.
type	string	No	earning, deduction, or employer_contribution.

Responses

Status	Meaning
200	A page of payroll entry components.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a payroll entry component

GET/v1/payroll_entry_components/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The payroll entry component.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such payroll entry component in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List salary slips

GET/v1/salary_slips

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
payroll_entry_id	string	No	Only slips for this entry.

Responses

Status	Meaning
200	A page of salary slips.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a salary slip

GET/v1/salary_slips/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The salary slip.
401	The API key is missing, malformed, revoked or expired.
402	The workspace's plan does not include Payroll (plan_upgrade_required).
403	The key does not carry the required scopes.
404	No such salary slip in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.