The following walkthrough is entirely server-side. If you have a QuickBooks Desktop installation for testing, you can use this guide to connect Conductor to read/write to/from your instance via our TypeScript library. If you do not, check out our guide on creating a free QuickBooks Desktop test instance.

Requirements

  1. A Conductor API key pair: one secret key, one publishable key. Please complete this form to join the private beta.
  2. Node.js v16 or later.

Create your first EndUser and IntegrationConnection

1

Install Conductor for Node.js

npm install conductor-node
2

Create an EndUser and save its ID to your database

An EndUser is a user of your application for whom we are creating an IntegrationConnection. Each EndUser can represent an individual or an entire company/organization of multiple users within your application. You can attach one or more IntegrationConnections to this EndUser.

After you create your EndUser, you must save the EndUser’s id to your database for sending requests to their IntegrationConnections in the future.

Include the following code on your server to create an EndUser:

import Conductor from "conductor-node";
const conductor = new Conductor("{{YOUR_SECRET_KEY}}");

const endUser = await conductor.endUsers.create({
  // Your end-user's unique ID from _your_ database. Must be distinct from
  // your other EndUsers. Can be anything you want if you are just testing.
  sourceId: "{{UNIQUE_ID_FROM_YOUR_DB}}",
  // Your end-user's email address.
  email: "{{END_USER_EMAIL}}",
  // Your end-user's company name shown elsewhere in Conductor.
  name: "{{END_USER_NAME}}",
});

This API call will return the newly created EndUser object, for example:

Example EndUser response
{
  // ❗❗ Save this value to your database!
  id: "end_usr_1234567abcdefg",
  sourceId: "12345678-abcd-abcd-example-1234567890ab",
  email: "bob@bigconstruction.com",
  name: "Big Construction Co.",
  createdAt: "2022-11-16 23:51:08.996+00"
}
3

Create an AuthSession

Before you can read/write data to/from an EndUser’s IntegrationConnection, your EndUser must complete the connection authentication flow. The following operation creates a session and returns a URL to redirect your end-user.

// ... continued from above

const authSession = await conductor.authSessions.create({
  publishableKey: "{{YOUR_PUBLISHABLE_KEY}}",
  // Use `endUser.id` from above.
  endUserId: endUser.id,
});
console.log("Complete the auth flow:", authSession.authFlowUrl);
Example AuthSession response
{
  id: "int_conn_auth_sess_1234567abcdefg",
  endUserId: "end_usr_1234567abcdefg",
  clientSecret: "auth_sess_client_secret_1234567abcdefg",
  expiresAt: "2022-11-16 23:51:08.996+00",
  // 👇 Visit this URL to launch the authentication flow.
  authFlowUrl: "https://connect.conductor.is/qbd/auth_sess_client_secret_1234567abcdefg?key={{YOUR_PUBLISHABLE_KEY}}"
}
4

Complete the authentication flow

Visit the returned authSession.authFlowUrl in your browser on the same computer or instance as your QuickBooks Desktop installation. This authentication flow will guide you through connecting your QuickBooks Desktop instance to Conductor.

Conductor authentication flow for QuickBooks Desktop
5

You're done!

After completing the authentication flow, you can access your QuickBooks Desktop instance through the Conductor library. The following example fetches a list of customers from your QuickBooks Desktop instance.

// ... continued from above

const qbdCustomers = await conductor.qbd.customer.query(endUser.id);
console.log("QBD customers:", qbdCustomers);
Example QBD response
[
  {
    ListID: '80000001-1693947446',
    TimeCreated: '2023-09-05T13:57:26-07:00',
    TimeModified: '2023-09-17T18:13:59-07:00',
    EditSequence: 1694999639,
    Name: "Annie's Alligators",
    FullName: "Annie's Alligators",
    IsActive: true,
    Sublevel: 0,
    Balance: 35693.49,
    TotalBalance: 35693.49,
    JobStatus: 'None'
  },
  {...},
  {...}
]