> ## 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.
# Create Customer
> Create a customer in QuickBooks.
## OpenAPI
````yaml /api-reference/v1/openapi.json post /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:
post:
tags:
- Pre-built Queries
summary: Create Customer
description: Create a customer in QuickBooks.
operationId: createCustomer
parameters:
- name: connection_id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the connection to use for customer creation
- name: request_id
in: query
required: false
schema:
$ref: '#/components/schemas/request_id'
- name: webhook_url
in: query
required: false
schema:
$ref: '#/components/schemas/webhook_url'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
maxLength: 41
description: >-
Customer name as it appears in the QuickBooks customer list
(must be unique)
is_active:
type: boolean
description: Whether the customer is active
class_list_id:
type: string
description: Optional class ListID
parent_list_id:
type: string
description: >-
Optional parent customer/job ListID, to create this customer
as a sub-customer or job
company_name:
type: string
maxLength: 41
description: Optional company name
salutation:
type: string
maxLength: 15
description: Optional salutation (e.g. Mr., Ms., Dr.)
first_name:
type: string
maxLength: 25
description: Optional first name
middle_name:
type: string
maxLength: 5
description: Optional middle name/initial
last_name:
type: string
maxLength: 25
description: Optional last name
suffix:
type: string
description: Optional name suffix (e.g. Jr., Sr.)
job_title:
type: string
maxLength: 41
description: Optional job title
bill_address:
type: object
description: Optional bill-to address
properties:
addr1:
type: string
addr2:
type: string
addr3:
type: string
addr4:
type: string
addr5:
type: string
city:
type: string
state:
type: string
postal_code:
type: string
country:
type: string
note:
type: string
ship_address:
type: object
description: Optional ship-to address
properties:
addr1:
type: string
addr2:
type: string
addr3:
type: string
addr4:
type: string
addr5:
type: string
city:
type: string
state:
type: string
postal_code:
type: string
country:
type: string
note:
type: string
ship_to_addresses:
type: array
description: Optional additional ship-to addresses (up to 50)
items:
type: object
required:
- name
properties:
name:
type: string
description: Label for this ship-to address
addr1:
type: string
addr2:
type: string
addr3:
type: string
addr4:
type: string
addr5:
type: string
city:
type: string
state:
type: string
postal_code:
type: string
country:
type: string
note:
type: string
default_ship_to:
type: boolean
description: Whether this is the default ship-to address
print_as:
type: string
maxLength: 41
description: >-
Optional name to print on checks and invoices, if different
from name
phone:
type: string
maxLength: 21
description: Optional phone number
mobile:
type: string
maxLength: 21
description: Optional mobile phone number
pager:
type: string
maxLength: 21
description: Optional pager number
alt_phone:
type: string
maxLength: 21
description: Optional alternate phone number
fax:
type: string
maxLength: 21
description: Optional fax number
email:
type: string
maxLength: 1023
description: Optional email address
cc:
type: string
maxLength: 1023
description: Optional CC email address
contact:
type: string
maxLength: 41
description: Optional primary contact name
alt_contact:
type: string
maxLength: 41
description: Optional alternate contact name
additional_contacts:
type: array
description: >-
Optional additional named contact methods (e.g. social
handles)
items:
type: object
required:
- contact_name
- contact_value
properties:
contact_name:
type: string
maxLength: 40
description: Label for this contact method (e.g. "Twitter")
contact_value:
type: string
maxLength: 255
description: Value for this contact method (e.g. "@acme")
contacts:
type: array
description: Optional additional named contacts at this customer
items:
type: object
required:
- first_name
properties:
salutation:
type: string
first_name:
type: string
middle_name:
type: string
last_name:
type: string
job_title:
type: string
customer_type_list_id:
type: string
description: Optional customer type ListID
terms_list_id:
type: string
description: Optional payment terms ListID
sales_rep_list_id:
type: string
description: Optional sales rep ListID
open_balance:
type: string
description: Optional opening balance as a decimal string
open_balance_date:
type: string
format: date
description: >-
Optional opening balance date (YYYY-MM-DD), required if
open_balance is set
sales_tax_code_list_id:
type: string
description: Optional sales tax code ListID
item_sales_tax_list_id:
type: string
description: Optional tax item or tax group ListID
sales_tax_country:
type: string
enum:
- Australia
- Canada
- UK
- US
description: Optional sales tax country
resale_number:
type: string
maxLength: 15
description: Optional resale number
account_number:
type: string
maxLength: 99
description: Optional account number shown on customer statements
credit_limit:
type: string
description: Optional credit limit as a decimal string
preferred_payment_method_list_id:
type: string
description: Optional preferred payment method ListID
credit_card_info:
type: object
description: Optional credit card on file
properties:
credit_card_number:
type: string
expiration_month:
type: integer
minimum: 1
maximum: 12
expiration_year:
type: integer
name_on_card:
type: string
credit_card_address:
type: string
credit_card_postal_code:
type: string
job_status:
type: string
enum:
- Awarded
- Closed
- InProgress
- None
- NotAwarded
- Pending
description: Optional job status, if this customer represents a job
job_start_date:
type: string
format: date
description: Optional job start date (YYYY-MM-DD)
job_projected_end_date:
type: string
format: date
description: Optional projected job end date (YYYY-MM-DD)
job_end_date:
type: string
format: date
description: Optional actual job end date (YYYY-MM-DD)
job_desc:
type: string
maxLength: 99
description: Optional job description
job_type_list_id:
type: string
description: Optional job type ListID
notes:
type: string
maxLength: 4095
description: Optional freeform notes
additional_notes:
type: array
description: Optional dated notes to attach to the customer
items:
type: string
maxLength: 4095
is_statement_with_parent:
type: boolean
description: >-
Whether to include this job's transactions on the parent
customer's statement (only applies to jobs)
delivery_method:
type: string
enum:
- Email
- Fax
- Print
description: Optional delivery method
preferred_delivery_method:
type: string
enum:
- None
- Email
- Fax
description: Optional preferred delivery method
price_level_list_id:
type: string
description: Optional price level ListID
external_guid:
type: string
description: >-
Optional external GUID for cross-referencing this customer
in another system
tax_registration_number:
type: string
maxLength: 30
description: Optional tax registration number (e.g. VAT number)
currency_list_id:
type: string
description: Optional currency ListID, for multi-currency companies
example:
name: Acme Co
company_name: Acme Corporation
first_name: John
last_name: Doe
bill_address:
addr1: 123 Main St
city: Austin
state: TX
postal_code: '78701'
phone: 512-555-0100
email: billing@acme.example
terms_list_id: 80000014-1234567890
responses:
'202':
description: >-
Customer create request 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'
'422':
$ref: '#/components/responses/UnprocessableEntity'
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 absolute http or https URL to receive a webhook when the
request is completed. It may not contain a username or password, and in
production it may not point at localhost or a private, loopback or
link-local address. A `qube listen` URL must be one of this app's.
maxLength: 2048
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
- timed_out
- discarded
description: >-
Current state of the queued request. `timed_out`: no answer came
back (the customer's computer lost its connection, or QuickBooks or
the Web Connector was closed, mid-request), so QuickBooks may still
have applied it. `discarded`: it was discarded before the Web
Connector picked it up, so QuickBooks never got it.
page:
type: integer
example: 1
description: >-
The page number, for a multi-page (iterated) response; `1` for a
request that isn't iterated
original_request_id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
description: >-
The id of the first page of this request's iteration, the same on
every page of it: equal to `id` on the first page itself, and on a
request that isn't iterated
iteration_state:
type: string
enum:
- not_applicable
- continue
- done
- max_sandbox_iterations_reached
description: >-
Whether this response is part of an ongoing iteration, and if so,
whether more pages remain. Use this (not `state`) to tell whether a
multi-page response is complete.
request_types:
type: array
items:
type: string
example:
- CustomerQueryRq
description: The qbXML request type(s) in `request_xml`
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:
requestID: '1'
children:
- name: MaxReturned
text: '100'
response_xml:
type: string
nullable: true
example: >-
80000001-1234567890Sample
Customer
description: >-
The QBXML response from QuickBooks. One answer can be at most 4 MB
as the Web Connector sends it, about 3 MB of qbXML; QuickBooks'
answer over that isn't kept: this is null and `error.error_type` is
`response_too_large`. A webhook whose body would be over 1 MB is
sent without it: it is null there, `response_xml_omitted` is true,
and `links.self` is the URL to GET the request from, this field
included.
response_json:
type: array
items:
type: object
nullable: true
description: >-
The response payload in JSON format, if request is completed:
QuickBooks' qbXML answer as JSON, element for element. Each `*Rs`
element carries QuickBooks' `@statusCode`, `@statusSeverity` and
`@statusMessage`. `Info` is a success. `Warn` means QuickBooks
carried the request out but warned about something, and the `*Ret`
it answered with is still there: for example `@statusCode` 530, `The
field "Memo" is not supported by this implementation.`, means the
record was saved without that field. `Error` means QuickBooks
refused it.
webhook_url:
type: string
format: uri
nullable: true
example: https://example.com/webhook
description: >-
URL to receive a webhook when the request is completed. The webhook
carries the request as it then is, `response_xml` and
`response_json` included, so it is at most about twice the size
limit on one answer (see `response_xml`).
webhook_attempts:
type: array
items:
type: object
properties:
status:
type: string
enum:
- succeeded
- failed
description: >-
Whether the webhook endpoint accepted this delivery (a 2xx
answer)
sent_at:
type: string
format: date-time
description: When this delivery was attempted
error:
type: string
nullable: true
description: Why the delivery failed (`null` when it succeeded)
attempted_at:
type: string
format: date-time
description: 'Not sent: the time of an attempt is `sent_at`'
deprecated: true
response:
type: string
description: >-
Not sent: the outcome of an attempt is `status`, and a
failure's reason is `error`
deprecated: true
required:
- status
- sent_at
description: Every webhook delivery attempt for this request, newest first
webhook_error:
type: string
nullable: true
description: Error message if webhook delivery failed
error:
type: object
nullable: true
properties:
error_type:
type: string
enum:
- xml_error
- quickbooks_connection_error
- quickbooks_business_error
- unexpected_error
- response_too_large
- outcome_unknown
- timed_out
- discarded
description: >-
Where it failed. `timed_out`: no answer came back, and
QuickBooks may still have applied the request, so look before
sending it again. `discarded`: QuickBooks never got it.
`response_too_large`: QuickBooks answered, but with more than
QuBe Sync accepts for one answer (4 MB as the Web Connector
sends it, about 3 MB of qbXML), so `response_xml` and
`response_json` are null. QuickBooks ran the request: page the
query (`iterate`, or `iterator="Start"` with `` in
`request_xml`) or narrow it, and for a write, look before
sending it again. `outcome_unknown`: a write the Web Connector
answered with an error in place of QuickBooks' answer, so
whether QuickBooks applied it is not known: look in QuickBooks
before sending it again. A query that fails that way is
`unexpected_error`, and can be sent again.
message:
type: string
description: >-
The raw message from QuickBooks or the Web Connector; for
`timed_out` and `discarded`, which neither sent, QuBe Sync's own
user_message:
type: string
description: A friendly message for the end user
error_code:
type: integer
nullable: true
description: QuickBooks' statusCode, for a business error
hresult:
type: string
nullable: true
description: The Web Connector's HRESULT, for a connection or XML error
debug_message:
type: string
nullable: true
description: Which element of the request the value came from, when known
code:
type: string
description: 'Not sent: QuickBooks'' status code is `error_code`'
deprecated: true
details:
type: object
description: Not sent
deprecated: true
description: >-
Set when `state` is `error`, `retryable`, `timed_out` or
`discarded`. A `timed_out` request's `error_type` is `timed_out`,
and a `discarded` one's `discarded`, unless the request was
`retryable` when it was discarded: then it keeps the connection
error that held it up.
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
pages:
type: string
format: uri
example: >-
/api/v2/connections/123e4567-e89b-12d3-a456-426614174000/queued-requests/550e8400-e29b-41d4-a716-446655440000/pages
description: >-
The pages of this request's iteration, oldest first. A v2 route
(`GET
/api/v2/connections/{connection_id}/queued-requests/{id}/pages`,
documented in the v2 API reference): v1 has none of its own, and
the same API key works there. It answers a page of them at a
time (`page`, `page_size`, at most 100) with a `meta` block, and
its rows are rendered as v1 renders this request.
required:
- self
- ui
- connection_ui
inserted_at:
type: string
format: date-time
example: '2023-01-01T12:00:00Z'
description: When the request was queued, UTC ISO 8601
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:
description: >-
What a refused request answers with. The one key is errors, and its
shape says what went wrong: a sentence when the endpoint explains the
refusal in words (a parameter the operation does not take, a key already
taken, a run that has already ended); an object with detail, and a code
when there is one, when the request named nothing that exists or may not
do what it asked (402, 403, 404, and a CLI session's 401), or an answer
to a run's question was refused (the decisions endpoint's 400, 409 and
422, which always carry a code to branch on); an object of fields, each
a list of messages, when a record failed validation and nothing was
saved; a list of {path, message} problems when a submitted document or
input fails validation. A request without a usable API key gets a 401
Basic challenge with the plain-text body Unauthorized, not JSON.
properties:
errors:
oneOf:
- example: 'unknown parameter: "emial"'
title: A sentence
type: string
- properties:
code:
example: read_only_session
type: string
detail:
example: Not Found
type: string
required:
- detail
title: Detail and code
type: object
- additionalProperties:
items:
type: string
type: array
example:
redirect_url:
- must be a valid URL
title: Field by field
type: object
- items:
properties:
message:
example: is required
type: string
path:
example: input.customer
type: string
required:
- path
- message
type: object
title: Located problems
type: array
required:
- errors
type: object
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors: 'unknown parameter: "emial"'
Unauthorized:
description: >-
No usable API key. The key is Basic auth, so the answer is the
challenge, with the plain-text body Unauthorized rather than JSON.
headers:
WWW-Authenticate:
schema:
type: string
example: Basic realm="Application"
content:
text/plain:
schema:
type: string
example: Unauthorized
NotFound:
description: The requested resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
detail: Not Found
UnprocessableEntity:
description: >-
A field failed validation, field by field, and nothing was queued: such
as a `webhook_url` that is not an absolute http or https URL, carries a
username or password, or (in production) points at localhost or a
private address.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
errors:
webhook_url:
- must be an http or https URL
securitySchemes:
apiKey:
type: http
scheme: basic
description: Use your app's API_KEY as the username, and leave the password blank
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.