Getting Started

Everything a user can do in QBO is an operation on a module, and every operation is reachable through one route pattern. Learn the pattern once and it applies to every page in Learn’s developer views.

The route pattern

Route	Use it to
/api/{module}/{operation}	Run an operation synchronously on the web server, for example /api/attachment/search.
/api/{module}/queue/{operation}	Queue the operation for an app server. Use it for long-running and batch work.
/api/{module}/{operation}/{id}	Run an operation on one record, for example /api/contact/select/42.
/api/{module}/{id}	Address one record by ID.
/api/{parentModule}/{parentId}/{module}/{operation}	Run an operation in the scope of a parent record, for example the documents on contact 1: /api/contact/1/attachment/search.

{module} is the record type (class), such as contact, attachment, message, or report, and {operation} is the method, such as search, save, generate, or calculate. Some operations span several segments, for example /api/organization/schedule/listen. Parameters go in the query string or the request body.

Configuration uses the same operations as method signatures, {ClassName}/{Operation}?{Parameters}, in workflow steps, schedules, and templates. A signature you see in configuration maps directly to an API call:

GET /api/contact/save?FirstName=Adam&LastName=Apple
GET /api/attachment/generate?Template=Welcome Letter&Object=Contact&ObjectID=1

Output formats

Add Output to choose the response format:

Value	Returns
Xml	XML (the native format for most operations)
Json / JsonP	JSON, or JSONP for cross-origin script use
Html / XHtml	Rendered HTML, optionally through an XSLT named in Transform
Csv	Comma-separated values, for search and report results

GET /api/contact/search?LastName=Apple&Output=Json

Authenticate with an API key

System-to-system calls authenticate with an API key issued to a QBO user account. Send it in the X-ApiKey header:

GET /api/contact/search?LastName=Apple&Output=Json
X-ApiKey: {your API key}

The call runs as that user, with that user’s roles and partner (extranet) security, exactly as if they were signed in. Give each integration its own account with only the permissions it needs. Key management, including expiry, usage limits, and IP restrictions, is covered in Security.

Caution

QBO also accepts the key as an ApiKey parameter, but query strings end up in logs and browser history. Use the header.

Queue long-running work

Anything that touches many records, calls a slow outside service, or generates large files belongs on a queue:

GET /api/attachment/queue/generate?Template=Welcome Letter&Object=Contact&ObjectID=1

The web server returns immediately and an app server runs the operation. Queues, schedules, and the queue providers an installation can use are described in API & Architecture.

Where to go next

• API & Architecture: queuing, plugins, configuration, and how modules fit together.
• Templates: how templates behave when records are saved through the API.
• Document Management: a complete worked example of one module’s API.
• AI: AI operations, agents, batching, and cost tracking.

Parameters

The parameters shown are the commonly used ones. Check the operation’s method signature in source (paths listed under the page title) before relying on less common options.