Payroll Integration API Overview

The Payroll Integration API exposes an employer's organization, payroll, benefits, and job data through a single, consistent interface. Endpoints are grouped by feature into four routes — Organization, Payroll, Benefits, and Jobs.

This overview covers the concepts common to every endpoint: authentication, shared parameters, the response envelope, the recommended integration flow, and the error reference. Read it before working with any individual endpoint.

To use the following endpoints, you must first call the Auth method to obtain an access token. Include this token in your request header as a Bearer token. Refer to OAuth 2.0 Authentication for details on JWT-based authentication.

Common Parameters

These parameters appear on every endpoint.

Parameter	Location	Required	Description
X-TaxBandits-Version	Header	Yes	API version string. Use 1.0.0 for all current endpoints.
entity_ids	Query	Yes	The organization ID. Must be exactly one UUID.

The one exception is GET /organization/company/by-tin, which is looked up by a tin query parameter instead of entity_ids.

Response Envelope Format

Every response — success or failure — is wrapped in a standard envelope. The actual data you need is always inside the response field.

Success

{
  "status": "SUCCESS",
  "status_code": 200,
  "message": "Request processed successfully",
  "response": { }
}

Failure

{
  "status": "FAILURE",
  "status_code": 400,
  "message": "Bad request",
  "errors": {
    "code": "BAD_REQUEST",
    "message": "entity_ids must be a valid UUID",
    "requestId": "a3f1c2d4-11bb-4e6a-9c0d-f83a57e12345"
  }
}

The errors.requestId is a unique ID for the request — include it when contacting support so the team can correlate logs.

Validation failure (write endpoints) — when a request body field fails validation, the response uses a structured details array so you can see every failing field at once:

{
  "status": "FAILURE",
  "status_code": 400,
  "message": "Bad request",
  "errors": {
    "code": "VALIDATION_FAILED",
    "message": "One or more fields failed validation",
    "requestId": "a3f1c2d4-11bb-4e6a-9c0d-f83a57e12345",
    "details": [
      { "field": "description", "code": "REQUIRED_DESCRIPTION", "message": "description is required" },
      { "field": "effective_date", "code": "INVALID_DATE", "message": "effective_date must be a valid date in YYYY-MM-DD format" }
    ]
  }
}

All monetary amounts are in cents (e.g. 500000 = $5,000.00). Percentage amounts are in basis points (e.g. 400 = 4%).

Integration Flow

Data flows between endpoints — IDs returned by one call are used as inputs to the next.

• Business → entity_ids — your organization ID (used on every request).
• Organization — GET /organization/directory returns individual_id[], used by POST /organization/individual and POST /organization/employment.
• Payroll — GET /payroll/payment returns payment_id[] (used by POST /payroll/pay-statement); GET /payroll/pay-groups returns pay_group_id[] (used by GET /payroll/pay-groups/{pay_group_id}).
• Benefits — create/register a benefit → benefit_id + job_id; enroll/unenroll individuals → job_id.
• Jobs — GET /jobs/manual/{job_id} uses the job_id returned by any write operation to confirm the result.

Error Reference

HTTP Status	Error Code	When it occurs
400	BAD_REQUEST	Missing or invalid parameter/path value.
400	VALIDATION_FAILED	One or more request body fields are invalid (see details[]).
401	UNAUTHORIZED	Bearer token is missing or invalid.
404	NOT_FOUND	The requested resource does not exist.
207	(Multi-Status)	Mixed results when filtering individuals — check per-item code fields.
500	INTERNAL_SERVER_ERROR	Unexpected server error.