Use cases

Here are use cases that demonstrate how to use the Time API for employees and contractors, specifically how to create the following:

App integration

The following figure provides an overview of how to integrate the Time API with your app.

qbo/docs/workflows/track-time/time-integration-diagram.png
qbo/docs/workflows/track-time/time-integration-diagram.png

x

Set up your environment

1. Set up your app on the Intuit Developer Portal

Since there is no sandbox available, use a production QuickBooks company to test with and create an app on the developer portal. When you create your app, make sure you review the settings for your app: endpoints, scopes, and required headers.

2. Get your app credentials

Get the client ID and client secret for your app. You’ll use these to connect your app to services such as OAuth 2.0.

3. Set up authorization

If you haven’t already, set up OAuth 2.0 for your app.

Note

Note: Use tokens generated using scopes mentioned above in the authorization header for all other calls shown here.

Pre-check

For some of the use cases described here, your company must support projects. Query the QuickBooks Online Accounting API Preferences resource and check Preferences.OtherPrefs.NameValue to determine if projects are supported for your company. Ensure that ProjectsEnabled is set to true.

The following shows an example response:

1
2
3
4
5
6
7
8
{
 "Name": "TimeTrackingFeatureEnabled",
 "Value": "true"
}
{
 "Name": "ProjectsEnabled",
 "Value": "true"
}
Use case 1: Create a time activity with pay type and link it to a project

This use case is applicable if you are enrolled in QuickBooks Payroll and have Projects enabled.

Use the Create TimeActivity resource of the Accounting REST API to create a time activity by fetching and setting the following values:

  1. Fetch employee.id by querying the Employee resource in the Accounting API and set it in EmployeeRef of the TimeActivity object with the NameOf field set to Employee.
  2. Using the employee.id obtained from the above step, use payrollEmployeeCompensations (Query) to fetch the list of employee compensation IDs (compensation.id) and set it in PayrollItemRef of the TimeActivity object.
  3. Use projectManagementProject (Query) in the GraphQL API to fetch project.id and set it as the ProjectRef value of the TimeActivity object.
  4. Fetch customer.id by querying the Customer resource in the Accounting API and set it as the CustomerRef value in the TimeActivity object.
  5. Fetch item.id by querying the Item resource in the Accounting API and set it in the TimeActivity object.

Sample request payload

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
  {
      "TxnDate": "2024-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": "Construction:DailyWork"
  }
Use case 2: Create time activity with pay type

This use case is applicable for customers who are enrolled in QuickBooks Payroll and do not have Projects enabled in QuickBooks Online.

Use the Create TimeActivity resource of the Accounting REST API to create a time activity by fetching and setting the following values:

  1. Fetch employee.id by querying the Employee resource in the Accounting API and set it in EmployeeRef in the TimeActivity object with NameOf field set to Employee.
  2. Fetch compensation.id using payrollEmployeeCompensations (Query) in the GraphQL API and set it as the PayrollItemRef value in the TimeActivity object.

Sample request payload

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  {
      "TxnDate": "2024-08-01T12:00:00Z",
      "NameOf": "Employee",
      "EmployeeRef": { "value": "1" },
      "PayrollItemRef": {
          "value": "626270109"
      },
      "Hours": 8,
      "Minutes": 0,
      "Description": "Construction:TimeOff"
  }
Use case 3: Create time activity and link to a project

This use case is applicable for customers who are not enrolled in QuickBooks Payroll and have Projects enabled in QuickBooks Online.

Use the Create TimeActivity resource of the Accounting REST API to create a time activity by fetching and setting the following values:

  1. Fetch employee.id by querying the Employee resource in the Accounting API and set it in EmployeeRef in the TimeActivity object with NameOf field set to Employee.
  2. Fetch item.id by querying the the Item resource in the Accounting API and set it in ItemRef in the TimeActivity object.
  3. Fetch project.id using projectManagementProject (Query) in the GraphQL API and set it in ProjectRef in the TimeActivity object.
  4. Fetch customer.id by querying the Customer resource from the Accounting API and set it as the CustomerRef value in the TimeActivity object.

Sample request payload

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
  {
      "TxnDate": "2024-08-01T12:00:00Z",
      "NameOf": "Employee",
      "EmployeeRef": { "value": "1" },
      "ItemRef": { "value": "1" },
      "CustomerRef": {
          "value": "2"
      },
      "ProjectRef": {
          "value":"416296152"
      },
      "Hours": 8,
      "Minutes": 0,
      "Description": "Construction:DailyWork"
  }
Use case 4: Create a time entry for an employee

This use case is applicable for the customers who are not enrolled in QuickBooks Payroll and do not have Projects enabled in QuickBooks Online.

Use the Create TimeActivity resource of the Accounting REST API to create a time activity by fetching and setting the following values:

  1. Fetch employee.id by querying the Employee resource in the Accounting API and set it in EmployeeRef in the TimeActivity object with the NameOf field set to Employee.
  2. Fetch item.id by querying the Item resource in the Accounting API and set it as the ItemRef value in the TimeActivity object.

Sample request payload

1
2
3
4
5
6
7
8
9
  {
      "TxnDate": "2024-08-01T12:00:00Z",
      "NameOf": "Employee",
      "EmployeeRef": { "value": "1" },
      "ItemRef": { "value": "1" },
      "Hours": 8,
      "Minutes": 0,
      "Description": "Construction:DailyWork"
  }
Use case 5: Create time activity for a contractor

This use case is applicable to track time for contractors and for the customers who do not have Projects enabled.

Use the Create TimeActivity resource of the Accounting REST API to create a time activity by fetching and setting the following values:

  1. Fetch vendor.id by querying the Vendor resource in the Accounting API and set it as VendorRef in the TimeActivity object with NameOf set to Vendor.
  2. Fetch item.id by querying the Item resource in the Accounting API and set it as the ItemRef value in the TimeActivity object.

Sample request payload

1
2
3
4
5
6
7
8
9
  {
      "TxnDate": "2024-08-01T12:00:00Z",
      "NameOf": "Vendor",
      "VendorRef": { "value": "5" },
      "ItemRef": { "value": "1" },
      "Hours": 8,
      "Minutes": 0,
      "Description": "Construction:DailyWork"
  }
Use case 6: Create time activity for a contractor and link it to a project

This use case is applicable to track time for contractors and for customers who have Projects enabled.

Use the Create TimeActivity resource of the Accounting REST API to create a time activity by fetching and setting the following values:

  1. Fetch vendor.id by querying the Vendor resource in the Accounting API, and set it in VendorRef of the TimeActivity object with NameOf set to Vendor.
  2. Fetch project.id using projectManagementProject (Query) in the GraphQL API and set it as the ProjectRef value in the TimeActivity object.
  3. Fetch customer.id by querying the Customer resource in the Accounting API and set it as the CustomerRef value in the TimeActivity object.

Sample request payload

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
  {
      "TxnDate": "2024-08-01T12:00:00Z",
      "NameOf": "Vendor",
      "VendorRef": { "value": "5" },
      "CustomerRef": {
          "value": "2"
      },
      "ProjectRef": {
          "value":"416296152"
      },
      "ItemRef": { "value": "1" },
      "Hours": 8,
      "Minutes": 0,
      "Description": "Construction:DailyWork"
  }
Independent contractors

For vendors who are independent contractors, reference the Vendor1099 field of the Vendor object, and it set to true.