# End users and connections
Source: https://www.desktopaccountingapi.com/docs/connect/end-users/

> Create, find, update and delete end users, read their connection details, and decide how to map your customers to QuickBooks company files.

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

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

```sh
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:

```json
{
  "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

After setup starts, the end user carries one connection:

```json
"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](https://www.desktopaccountingapi.com/docs/connect/connection-status/).
- `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

`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

`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

`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](https://www.desktopaccountingapi.com/docs/help/guides/remove-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

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

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

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](https://www.desktopaccountingapi.com/docs/connect/connection-status/#company-file-mismatch).

## Related

- [Connect an end user](https://www.desktopaccountingapi.com/docs/connect/setup-flow/) creates the setup link.
- [Mapping your objects to QuickBooks](https://www.desktopaccountingapi.com/docs/quickbooks/mapping-objects/) covers matching your customers, products and invoices to QuickBooks records.