# Retrieve the connection
Source: https://www.desktopaccountingapi.com/docs/api/reference/operations/endusersretrieveconnection/

`GET https://api.desktopaccountingapi.com/v1/end-users/{id}/connection`

Operation ID: `endUsers.retrieveConnection`. Tag: End users.

Returns the end user's QuickBooks Desktop connection: its status, the Web Connector installs issued for it, company file mismatches in the last 30 days and whether QuickBooks shares personal data. The connection exists once the first auth session is created; before that the call returns `409 INTEGRATION_CONNECTION_NOT_SET_UP`.

Authentication: `Authorization: Bearer <secret key>`.

Example request:

```sh
curl https://api.desktopaccountingapi.com/v1/end-users/eu_01j9x4m6v4c8k2t7q0r5s3w1zb/connection \
  -H "Authorization: Bearer $DAAPI_SECRET_KEY"
```

## Path parameters

- `id` (string, required): Unique identifier for the end user. example `eu_01j9x4m6v4c8k2t7q0r5s3w1zb`.

## Responses

### 200

The connection.

Body (application/json): object (EndUserConnection).

- `id` (string, required): Unique identifier for the connection. example `conn_01j9x4m6v4c8k2t7q0r5s3w1zc`.
- `objectType` (string, required): Always `integration_connection`. one of `integration_connection`.
- `createdAt` (string (date-time), required): When the connection was created. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
- `integrationSlug` (string, required): The integration this connection uses. one of `quickbooks_desktop`.
- `status` (string, required): Derived connection status. `pending_setup`: no Web Connector has finished setup. `online`: the Web Connector checked in recently and the last QuickBooks session opened. `quickbooks_unavailable`: the Web Connector checks in but QuickBooks could not be opened (`statusReason` holds the error code). `company_file_mismatch`: a different company file is open. `offline`: no recent check-in. `disabled`: turned off by the developer. one of `pending_setup`, `online`, `quickbooks_unavailable`, `company_file_mismatch`, `offline`, `disabled` (open: accept unknown values).
- `statusReason` (string, nullable, required): Code explaining a non-online status, when known: an error code (for example `QBD_ACCESS_NOT_GRANTED`), `QBD_QUICKBOOKS_NOT_RESPONDING` (the Web Connector checks in but QuickBooks does not answer, usually because a dialog is open) or `WEB_CONNECTOR_SCHEDULE_CHANGED`. With `online` it can be `QBD_FILE_MODE_CONFLICT`: QuickBooks reported a single-user/multi-user conflict and, for 2 minutes, the connection opens no session and synchronous requests fail fast with that code; or `WEB_CONNECTOR_SCHEDULE_CHANGED`. example `QBD_QUICKBOOKS_NOT_RESPONDING`.
- `lastRequestAt` (string, nullable, required): When the last request for this connection was made. UTC, ISO 8601.
- `lastSuccessfulRequestAt` (string, nullable, required): When the last request succeeded. UTC, ISO 8601.
- `lastHeartbeatAt` (string, nullable, required): When the Web Connector last checked in. UTC, ISO 8601.
- `companyFile` (object, nullable, required): The connected company file, once a session has opened.
  - `companyName` (string, nullable, required): Company name reported by QuickBooks.
  - `product` (string, nullable, required): QuickBooks product and version reported by QuickBooks. example `QuickBooks Enterprise Solutions: General Business 24.0`.
  - `qbxmlVersion` (string, nullable, required): qbXML version used with this company file. example `16.0`.
  - `country` (string, nullable, required): QuickBooks edition country. example `US`.
- `personalDataAccess` (string, required): Whether QuickBooks lets this connection read personal data (employee Social Security numbers, payroll details), as the Web Connector reported in the last verified session. `denied`: QuickBooks omits those fields, and employee responses carry a `QBD_PERSONAL_DATA_WITHHELD` warning for each one. `unknown`: no session has reported it yet. The QuickBooks Admin changes it under Edit > Preferences > Integrated Applications > Company Preferences > Properties; the new value shows after the next session. one of `allowed`, `denied`, `unknown` (open: accept unknown values); example `allowed`.
- `endUserId` (string, required): Unique identifier for the end user. example `eu_01j9x4m6v4c8k2t7q0r5s3w1zb`.
- `disabled` (boolean, required): Whether the connection is disabled. A disabled connection refuses Web Connector check-ins and fails new requests with `INTEGRATION_CONNECTION_DISABLED`.
- `setupCompletedAt` (string (date-time), nullable, required): When the first Web Connector install finished setup, or null. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
- `installs` (array of object (WebConnectorInstall), required): Web Connector installs (connector files) issued for this connection, newest first, at most 20.
  - `id` (string, required): Unique identifier for the Web Connector install (one connector file). example `ctr_01j9x4m6v4c8k2t7q0r5s3w1zg`.
  - `objectType` (string, required): Always `web_connector_install`. one of `web_connector_install`.
  - `status` (string, required): `active`: the install can check in. `replaced`: a newer install finished setup (for example on a new computer), or the setup flow issued a new connector file; its check-ins are refused. one of `active`, `replaced` (open: accept unknown values).
  - `createdAt` (string (date-time), required): When the setup flow issued the connector file. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
  - `passwordSet` (boolean, required): Whether the end user has been shown the Web Connector password for this install.
  - `setupCompletedAt` (string (date-time), nullable, required): When this install finished its first verified QuickBooks session, or null. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
  - `firstCheckInAt` (string (date-time), nullable, required): When the Web Connector first checked in with this install, or null. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
  - `lastCheckInAt` (string (date-time), nullable, required): When the Web Connector last checked in with this install, or null. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
  - `replacedAt` (string (date-time), nullable, required): When the install was replaced, or null while it is active. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
- `companyFileMismatches` (object, required): Company file mismatches in the last 30 days. `total` is 0 when there were none.
  - `total` (integer, required): Sessions in the last 30 days in which QuickBooks had a different company file open.
  - `groups` (array of object (CompanyFileMismatch), required): Grouped by the company file QuickBooks reported, most recent first.
    - `companyName` (string, nullable, required): The company QuickBooks had open instead of the connected one, when QuickBooks reported it.
    - `fileName` (string, nullable, required): The file name (without folders) QuickBooks had open, when known. example `Acme Copy.QBW`.
    - `inferred` (boolean, required): `true` when QuickBooks could not open the connected file (HRESULT 0x80040408), usually because another company file was open.
    - `count` (integer, required): Mismatched sessions in this group.
    - `firstAt` (string (date-time), required): The first mismatched session in this group. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.
    - `lastAt` (string (date-time), required): The latest mismatched session in this group. UTC, ISO 8601 with milliseconds. example `2026-10-05T16:03:59.002Z`.

### Errors

Every error body is the error object described at https://www.desktopaccountingapi.com/docs/errors/.

- `400`: The request is invalid. Codes: `UNKNOWN_HEADER`, `INVALID_PARAMETER`.
- `401`: The API key is missing or invalid. Codes: `API_KEY_MISSING`, `API_KEY_INVALID`.
- `404`: The object does not exist in this project. Codes: `RESOURCE_MISSING`.
- `409`: The request conflicts with the current state. Codes: `INTEGRATION_CONNECTION_NOT_SET_UP`.
- `429`: Too many requests. Codes: `RATE_LIMITED`.
- `500`: Unexpected server error. Codes: `INTERNAL_ERROR`.
- `503`: QuickBooks Desktop or the service is not available. Codes: `SERVICE_UNAVAILABLE`.