Migration Guide

Intuit is pleased to share the launch of the new QuickBooks Payroll API to access payroll data. If you are currently using our older APIs, you need to migrate to the new APIs.

If you are using the endpoint https://v4thirdparty.api.intuit.com/graphql, you are migrating from our Alpha API.

If you are using the endpoint https://public.api.intuit.com/2020-04/graphql, you are migrating from our Beta API.

The employee ID returned in the new API is in a new format and is not the same employee Id in existing APIs. For example, the employee Id returned from existing APIs is in a format similar to djQtLToxU5NjB65:0020715c71ba83 or djQtLToxU5NjB65:2. In the new API, the employee ID is numeric values such as 2 or 3. The old IDs are returned in the alternateIds.id field.

1. Read the employee roster for the company using this query:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

  {
    workerManagementEmployees {
      edges {
        node {
          id
          firstName
          middleName
          lastName
          alternateIds {
            id
            nameSpace
          }
        }
      }
      pageInfo {
        endCursor
        hasNextPage
        hasPreviousPage
        startCursor
      }
      totalCount
    }
  }

2. Map the new IDs against the alternateIds.id field that you already have stored.
3. Use the new IDs going forward.

If you currently use the com.intuit.quickbooks.payroll scope, you will be able to use the new APIs for your existing customers. When new customers connect to your app or when existing users reconnect to your app, include new scopes in your authorization call. The required scopes for each resource are described on the individual reference pages.

The following tables show how to map from beta fields to the new fields.

Use our QuickBooks Online API to read company information .