Skip to main content
GET
List payroll items

Authorizations

Authorization
string
header
required

Use your app's API key as the username, and leave the password blank

Headers

Idempotency-Key
string

Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers 201 with what the first call created, as it is now, marked Idempotent-Replayed: true, and queues nothing. The same key with a different request is a 422. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Path Parameters

connection_id
string<uuid>
required

The connection (a customer's QuickBooks company file) this request is queued for.

Query Parameters

request_id
string

Your own label for the request, sent to QuickBooks as its qbXML requestID and echoed in the raw answer (response_xml); optional, since the answer's webhook already carries the request's id.

meta_data
enum<string>
Available options:
MetaDataAndResponseData,
MetaDataOnly,
NoMetaData
active_status
enum<string>

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

Available options:
ActiveOnly,
All,
InactiveOnly
from_modified_date
string<date-time>

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

full_name
string[]

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

include_ret_element
enum<string>[]
Available options:
CalculatedBasedOn,
EditSequence,
ExpenseAccountRef,
IsActive,
IsTrackedByCustJob,
LiabilityAccountRef,
LiabilityPaymentSchedule,
Limit,
LimitTimePeriod,
ListID,
Name,
NetOrGross,
OvertimeMultiplier,
PaymentTemplateRef,
PayrollItemDetailTypeValue,
Rate,
RateChange,
RatePercent,
State,
TaxCalculatedBasedOn,
Taxability,
TimeCreated,
TimeModified,
VendorAccountNumber,
VendorRef,
W2TrackingTypeValue,
WageType
list_id
string[]

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

max_returned
integer

QuickBooks doesn't page this query: at most this many records come back, in one answer, with no sign of whether more matched. Leave it out for every match, in one answer; one over 4 MB as the Web Connector sends it, about 3 MB of qbXML isn't kept (error_type response_too_large), so narrow a large one with its filters.

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

Required range: x >= 1
name_filter
object

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

name_range_filter
object

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

to_modified_date
string<date-time>

Choose at most one of: list_id, or full_name, or the set (active_status, from_modified_date, max_returned, name_filter, name_range_filter, to_modified_date). Members of a set combine with each other, not with the other choices.

webhook_url
string<uri>

Where QuBe Sync POSTs the answered request (this same document with response_json filled in), signed with X-QUBE-Signature. Send one with every request: it is how answers are delivered. Optional only so a script can queue and look up links.self by hand. It must be an absolute http or https URL. 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.

Maximum string length: 2048

Callbacks

POST
{$request.query.webhook_url}answered

Body

application/json

POSTed to webhook_url as JSON, signed with X-QUBE-Signature (t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your app's webhook secret>).

app_id
string<uuid>
required

Your app's id.

app_name
string
required
error
object | null
required

Set when state is error, retryable, timed_out or discarded. error_type says where it failed: for a timed_out request it is timed_out, and for a discarded one discarded, unless the request was retryable when your app discarded it, which keeps the connection error that held it up. user_message is safe to show an end user; error_code is QuickBooks' own status code for a business error, hresult the Web Connector's for a connection/XML error; debug_message is for you.

id
string<uuid>
required

The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here.

page_request_id
string<uuid>
required

This page's own id. Equal to id except on later pages of an iterated query.

response_json
Success · object
required

QuBe Sync's summary of QuickBooks' answer. Only an Error severity from QuickBooks is status: "error" (and makes the request's state error), so a query that matched nothing is still success. A Warn severity is a success with warning beside it.

sandbox
boolean
required

Whether the app is a sandbox app.

state
enum<string>
required

response_received: QuickBooks accepted it; read response_json. error: it is over and QuBe Sync won't try again -- see error, and response_json.error for a QuickBooks business error; with error_type outcome_unknown a write may still have been applied, so look before sending it again. retryable: QuickBooks could not be reached and QuBe Sync keeps trying; show the customer error.user_message so they can fix it. timed_out: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, mid-request. QuickBooks may still have applied it, so look before sending it again. discarded: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. Both carry an error.

Available options:
response_received,
error,
retryable,
timed_out,
discarded
timestamp
integer
required

Unix seconds; the same t the signature covers.

iteration_state
enum<string>

continue: more pages will follow, each its own webhook. done: this was the last page. max_sandbox_iterations_reached: a sandbox app's page limit stopped the iteration.

Available options:
not_applicable,
continue,
done,
max_sandbox_iterations_reached

Present only with response_xml_omitted.

page
integer | null

The page number, when iterated.

response_xml
string | null

QuickBooks' raw qbXML answer. response_json is the same, summarized. 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: null, with response_xml_omitted true; fetch it from links.self.

response_xml_omitted
boolean

Present, and true, only when response_xml was left out to keep the body under 1 MB. response_json is still here; GET links.self for response_xml.

Response

2XX

Received. Anything else is retried with backoff for about 8 hours.

Response

Queued for the connection's Web Connector. Pass webhook_url and QuBe Sync POSTs the answer to it once QuickBooks has answered (see the answered callback: its own payload, not this document). links.self returns this document on demand, with response_json filled in.

data
object
required