Powerful time & payroll tracking with the Time API + Payroll Compensation

Managing and compensating employee time is a critical part of payroll workflows. Intuit’s new Time API with Payroll Compensation, introduced as one of the Premium APIs, empowers developers to extend QuickBooks Online Payroll’s robust time-tracking capabilities into their own apps.

Now, you can seamlessly access pay types such as salary, hourly, overtime, holiday and more, and create time entries enriched with payroll context.

Click here to learn more about partner tiers and upgrades.

In this post, we’ll cover

Why the Time API with Payroll Compensation matters
How it works (GraphQL + REST)
Example workflows for real use cases
Sample code and app integration references
Best practices and considerations

Why it matters

QuickBooks Online Payroll enables businesses to track work hours accurately against payroll-specific pay types, including regular hours, overtime and holiday rates. The Time API exposes that granularity, enabling:

Time entries tied to the correct payroll compensation types
Richer insights in time-based billing or reporting systems
Streamlined payroll automation and payroll item alignment

By coupling time tracking with payroll compensation awareness, your application becomes more trustworthy and useful to payroll-focused users.

How the API works

1. GraphQL endpoint for compensation types

To fetch available employee pay types, the API exposes the payrollEmployeeCompensations GraphQL query, protected by the payroll.compensation.read scope.

Important: Compensation data is only available for customers using QuickBooks Payroll.

Production GraphQL: https://qb.api.intuit.com/graphql
Note: Sandbox is currently not supported for this API

Required headers:

Authorization: Bearer <access_token>
Content-Type: application/json

2. REST endpoint for TimeActivity

Once you have the compensation type ID, submit time entries via the Accounting REST API using the TimeActivity resource:

POST https://quickbooks.api.intuit.com/v3/company/{realmId}/timeactivity?minorversion=70

This endpoint supports:

Employee references
Payroll item references (compensation IDs)
Optional project, customer and item linkage

Workflow examples

Use Case A: Time activity with pay type & project link

This workflow assumes both Payroll and Projects are enabled.

Steps:

{
  "TxnDate": "2025-08-01T12:00:00Z",
  "NameOf": "Employee",
  "EmployeeRef": { "value": "1" },
  "PayrollItemRef": { "value": "626270109" },
  "CustomerRef": { "value": "2" },
  "ProjectRef": { "value": "416296152" },
  "ItemRef": { "value": "1" },
  "Hours": 8,
  "Minutes": 0,
  "Description": "Daily Work"
}

Use Case B–F: Additional scenarios

With pay type, no project

{
  "EmployeeRef": { "value": "1" },
  "PayrollItemRef": { "value": "626270109" },
  "Hours": 8,
  "Minutes": 0,
  "Description": "Time Off"
}

Project only (no pay type)

{
  "EmployeeRef": { "value": "1" },
  "ProjectRef": { "value":"416296152" },
  "CustomerRef": { "value": "2" },
  "ItemRef": { "value": "1" },
  "Hours": 8,
  "Minutes": 0,
  "Description": "Daily Work"
}

Simple employee time entry

{
  "EmployeeRef": { "value": "1" },
  "ItemRef": { "value": "1" },
  "Hours": 8,
  "Minutes": 0,
  "Description": "Daily Work"
}

Contractor time entry

{
  "VendorRef": { "value": "5" },
  "ItemRef": { "value": "1" },
  "Hours": 8,
  "Minutes": 0,
  "Description": "Daily Work"
}

Contractor + project

{
  "VendorRef": { "value": "5" },
  "CustomerRef": { "value": "2" },
  "ProjectRef": { "value": "416296152" },
  "ItemRef": { "value": "1" },
  "Hours": 8,
  "Minutes": 0,
  "Description": "Daily Work"
}

Sample app reference

For hands-on examples, explore the official Intuit Developer repositories:

OAuth setup and scopes
GraphQL queries for compensation and employee data
REST workflows for TimeActivity entries

Browse sample repos

Considerations & limitations

No sandbox support: A production QuickBooks company is required
Scopes: Use payroll.compensation.read and other minimum required scopes
Feature availability: Check preferences such as ProjectsEnabled

Best practices

Verify feature flags before calling dependant APIs
Use GraphQL to fetch essential IDs before REST operations
Structure your TimeActivity payloads clearly
Apply least privilege with scopes

The final note

The Time API with Payroll Compensation empowers your application to capture time data with payroll-level precision. By blending GraphQL for compensation discovery with REST for time entry submission, you can manage complex workflows with ease.

Getting started by partner tier

Builder and Silver: Click here to upgrade
Gold and Platinum: Enable scopes under the Permissions tab in the developer portal