Skip to content
Desktop Accounting API

End users and connections

View as Markdown

An end user is one of your customers. Its connection links it to one QuickBooks Desktop company file. You create end users from your backend, usually when a customer turns on your QuickBooks integration.

One end user per company file

Section titled “One end user per company file”

Create one end user for each QuickBooks company file you need to reach. Most customers have one file. A customer who keeps separate books for two businesses needs two end users and goes through setup twice, once per file.

Use sourceId for your own identifier. It must be unique within the project, so a natural choice is your customer ID, or your customer ID plus a suffix when one customer has several files (cust_8812, cust_8812-retail).

Create an end user

Section titled “Create an end user”
Terminal window
curl https://api.desktopaccountingapi.com/v1/end-users \
  -H "Authorization: Bearer $DAAPI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4b9e1d2c-..." \
  -d '{"companyName":"Acme Supply","sourceId":"cust_8812","email":"ops@acme.example"}'
Field Rules
companyName 1 to 255 characters. The setup flow shows it: “Connect Acme Supply’s QuickBooks Desktop to Your App”.
sourceId 1 to 255 characters, unique within the project. A duplicate returns 400 INVALID_PARAMETER with param: "sourceId".
email A contact address for your records. We never send email to end users.

The response is the end user object:

{
  "id": "eu_01j9x4m6v4c8k2t7q0r5s3w1zb",
  "objectType": "end_user",
  "createdAt": "2026-10-05T16:03:59.002Z",
  "companyName": "Acme Supply",
  "sourceId": "cust_8812",
  "email": "ops@acme.example",
  "integrationConnections": []
}

Store id with your customer record. integrationConnections stays empty until you create the first setup link for the end user.

Read the connection

Section titled “Read the connection”

After setup starts, the end user carries one connection:

"integrationConnections": [
  {
    "id": "conn_01j9x5b7s2k8m4q6t0v3w5y7za",
    "objectType": "integration_connection",
    "createdAt": "2026-10-05T16:10:12.441Z",
    "integrationSlug": "quickbooks_desktop",
    "status": "online",
    "statusReason": null,
    "lastRequestAt": "2026-10-05T16:20:01.117Z",
    "lastSuccessfulRequestAt": "2026-10-05T16:20:01.117Z",
    "lastHeartbeatAt": "2026-10-05T16:20:09.003Z",
    "companyFile": {
      "companyName": "Acme Supply Co",
      "product": "QuickBooks Enterprise Solutions: General Business 24.0",
      "qbxmlVersion": "16.0",
      "country": "US"
    }
  }
]
  • status and statusReason describe the connection right now. See Connection status and health checks.
  • lastHeartbeatAt is the last Web Connector check-in. A recent heartbeat means the computer is on and the Web Connector is running. It does not prove QuickBooks can open the file.
  • companyFile is what QuickBooks reported in the last session: the company name inside the file (which can differ from your companyName), the QuickBooks product and version, and the qbXML version we use with it.

integrationConnections is an array so the shape can grow, but an end user has at most one connection today.

List and find end users

Section titled “List and find end users”

GET /v1/end-users returns end users newest first. It pages with limit (1 to 100, default 50) and cursor. These cursors come from our database, so unlike QuickBooks cursors they never expire.

To find the end user for one of your customers, keep the eu_ ID in your own database. The dashboard’s End users page also searches by company name, source ID or ID.

Update an end user

Section titled “Update an end user”

POST /v1/end-users/{id} changes companyName, sourceId or email. Send only the fields you want to change. Changing companyName affects future setup links; it does not rename anything in QuickBooks.

Delete an end user

Section titled “Delete an end user”

DELETE /v1/end-users/{id} permanently removes the end user, its connection, its Web Connector credentials and the stored request history for it. The customer’s Web Connector is refused at its next check-in and shows an authentication error. Ask the customer to remove the application from the Web Connector; Remove the connection has the steps.

Deleting cannot be undone. To reconnect the same customer later, create a new end user and run setup again.

Disable a connection

Section titled “Disable a connection”

From the dashboard you can disable a connection without deleting the end user, for example while a customer’s account is suspended. Calls for that end user return 403 INTEGRATION_CONNECTION_DISABLED, and the Web Connector on the customer’s computer is refused until you enable it again.

Move an end user to another project

Section titled “Move an end user to another project”

Owners and admins can move an end user to another project of the same organization and environment (test to test, production to production) from the dashboard, including a connected one. A move waits until no request is in flight. The connection, request history and Web Connector setup move with it, and open setup links for it are canceled.

Reset the company file

Section titled “Reset the company file”

When the customer moved, renamed or replaced the company file, POST /v1/end-users/{id}/reset-company-file tells the connection to use the file now open in QuickBooks. See Company file mismatch.

Section titled “Related”