> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qubesync.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Query Customers
> Executes a pre-built query to retrieve customer data from QuickBooks. Supports filtering by name, date range, and active status.
## OpenAPI
````yaml /api-reference/openapi.json get /connections/{connection_id}/customers
openapi: 3.0.0
info:
title: QuBe Sync API
description: Integrate with QuickBooks Desktop or QuickBooks Enterprise in a few steps.
version: 1.0.0
contact:
email: support@qubesync.com
servers:
- url: https://qubesync.com/api/v1
description: v1 API
- url: https://dev.qubesync.com/api/v1
description: Local development server
security: []
tags:
- name: Connections
description: Endpoints for managing QuickBooks connections
- name: Queued Requests
description: Endpoints for managing queued API requests
- name: Pre-built Queries
description: >-
Endpoints for executing pre-built queries against QuickBooks data. These
endpoints simplify common data retrieval operations by providing a
higher-level interface than the raw queued requests API. Each query is
executed asynchronously and returns a queued request ID that can be used
to check the status and retrieve results.
paths:
/connections/{connection_id}/customers:
get:
tags:
- Pre-built Queries
summary: Query Customers
description: >-
Executes a pre-built query to retrieve customer data from QuickBooks.
Supports filtering by name, date range, and active status.
operationId: queryCustomers
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the connection to use for the query
- name: request_id
in: query
required: false
schema:
$ref: '#/components/schemas/request_id'
- name: max_returned
in: query
required: false
schema:
type: integer
description: Maximum number of results to return
- name: include[]
in: query
required: false
schema:
type: array
items:
type: string
enum:
- FullName
- ListID
- etc
description: >-
List of fields for QuickBooks to include in the response. Full list
of possible values at
- name: name
in: query
required: false
schema:
type: string
description: Filter customers by name (partial match, case-insensitive)
- name: from_name
in: query
required: false
schema:
type: string
description: Filter customers with names starting from this value (inclusive)
- name: to_name
in: query
required: false
schema:
type: string
description: Filter customers with names up to this value (inclusive)
- name: from_modified_date
in: query
required: false
schema:
type: string
format: date-time
description: Filter customers modified after this date/time (ISO 8601 format)
- name: to_modified_date
in: query
required: false
schema:
type: string
format: date-time
description: Filter customers modified before this date/time (ISO 8601 format)
- name: active
in: query
required: false
schema:
type: string
enum:
- ActiveOnly
- InactiveOnly
- All
default: ActiveOnly
description: Filter customers by active status
- name: webhook_url
in: query
required: false
schema:
$ref: '#/components/schemas/webhook_url'
responses:
'202':
description: >-
Query accepted and queued for processing. Returns a queued request
object.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/QueuedRequest'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
security:
- apiKey: []
components:
schemas:
request_id:
type: string
description: >-
A custom ID that can be used to identify the request and response. This
could be your local ID for the request.
example: '1'
webhook_url:
type: string
format: uri
description: Optional URL to receive a webhook when the request is completed
QueuedRequest:
type: object
properties:
id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
description: Unique identifier for the queued request
state:
type: string
enum:
- waiting
- retryable
- ticketed
- sent
- response_received
- error
- discarded
description: Current state of the queued request
webhook_state:
type: string
enum:
- not_applicable
- pending
- succeeded
- failed
description: >-
State of the webhook delivery. Not applicable if webhook_url was not
provided.
request_xml:
type: string
example: >-
100
description: The QBXML request to be processed
request_json:
type: object
nullable: true
description: The request payload in JSON format (alternative to request_xml)
example:
version: '13.0'
request:
name: CustomerQueryRq
attributes:
request_id: '1'
children:
- name: MaxReturned
text: '100'
response_xml:
type: string
nullable: true
example: >-
80000001-1234567890Sample
Customer
description: The QBXML response from QuickBooks
response_json:
type: array
items:
type: object
nullable: true
description: The response payload in JSON format, if request is completed
webhook_url:
type: string
format: uri
nullable: true
example: https://example.com/webhook
description: URL to receive a webhook when the request is completed
webhook_attempts:
type: array
items:
type: object
properties:
attempted_at:
type: string
format: date-time
description: The timestamp when the webhook was attempted
response:
type: string
description: The response from the webhook endpoint or an error message
required:
- attempted_at
- response
description: List of webhook delivery attempts with timestamps and responses
webhook_error:
type: string
nullable: true
description: Error message if webhook delivery failed
error:
type: object
nullable: true
properties:
message:
type: string
code:
type: string
details:
type: object
description: Error details if the request failed processing
links:
type: object
properties:
self:
type: string
format: uri
example: >-
/api/v1/connections/123e4567-e89b-12d3-a456-426614174000/queued_requests/550e8400-e29b-41d4-a716-446655440000
ui:
type: string
format: uri
example: /app/queued_requests/550e8400-e29b-41d4-a716-446655440000
connection_ui:
type: string
format: uri
example: /app/connections/123e4567-e89b-12d3-a456-426614174000
required:
- self
- ui
- connection_ui
inserted_at:
type: string
format: date-time
example: '2023-01-01T12:00:00Z'
description: When the request was created
updated_at:
type: string
format: date-time
example: '2023-01-01T12:00:01Z'
description: When the request was last updated
connection_id:
type: string
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
description: ID of the connection this request belongs to
required:
- id
- connection_id
- state
- request_xml
Error:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: invalid_request
message:
type: string
example: The request was invalid
details:
type: object
description: Additional error details
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_request
message: The request was invalid
Unauthorized:
description: Authentication required or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
message: Authentication required
NotFound:
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: not_found
message: The requested resource was not found
securitySchemes:
apiKey:
type: http
scheme: basic
description: Use your app's API_KEY as the username, and leave the password blank
````