Skip to main content
Glama

QuBe Sync: QuickBooks Desktop API for developers

Create data ext def

create_data_ext_def
Read-onlyIdempotent

This request adds a data extension definition to the specified object type (e.g. Customer) so that extension data can be written to a particular object of that type (e.g., this customer, John Smith. A data extension definition must be created before data can be written to the data extension.

The data_ext_def_add wrapper from qbXML is also accepted. Returns the v2 request to send, and the webhook payload QuickBooks' answer arrives in (this operation's response_json: its data shape and the status codes to handle).

Possible errors (error.code / error.type; the call result explains each): 1030 unsupported_request, 3040 invalid_amount, 3070 string_too_long, 3150 missing_element, 3175 in_use, 3176 locked, 3180 cannot_save, 3210 invalid_value, 3220 not_authorized, 3231 request_not_processed, 3250 feature_not_enabled, 3260 insufficient_permission, 3261 personal_data_access_denied, 3262 payroll_subscription_required, 3263 read_only_access, 3264 merchant_services_subscription_required, 3270 missing_posting_account

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "data_ext_name": "<data_ext_name>",
      "data_ext_type": "<data_ext_type>",
      "owner_id": "<owner_id>"
    },
    "name": "create_data_ext_def"
  }
}

Input Schema

NameRequiredDescriptionDefault
owner_idYes`owner_id` identifies who owns the data extension. Use 0 for QuickBooks custom fields that appear in the UI, or use a GUID for private extensions owned by an app.
request_idNoYour 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`.
data_ext_nameYesThe name of the data extension. If this is a custom field, `data_ext_name` will be visible as a label in the QuickBooks user interface.
data_ext_typeYesThe field’s data type, which corresponds to a qbXML data type. In an IDataExtDefAdd request object, if this is a custom field, `data_ext_type` must be detSTR255TYPE.
include_qbxmlNoAlso return the qbXML this compiles to, for debugging. Not part of the v2 request.
assign_to_objectNo
include_ret_elementNo
data_ext_txn_requireNoIf `data_ext_txn_require` is true, this data extension field is required to be entered in transaction. The default value is false.
data_ext_list_requireNoIf `data_ext_list_require` is true, this data extension field is required to be entered in lists. The default value is false.
data_ext_format_stringNoThe string format required for the data extension.

Output Schema

NameRequiredDescriptionDefault
urlYesReplace {connection_id} with the customer's connection.
bodyYesThe JSON body: the arguments you passed.
qbxmlNoThe qbXML it compiles to. Only with include_qbxml.
methodYes
headersYesSend with the request. Resent unchanged when no 201 came back, it answers with the request already queued.
webhookYesJSON Schema of the payload POSTed to webhook_url once QuickBooks answers, with this operation's response_json (data shape and status codes).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

C2.9/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description frames the call as a write ('adds a data extension definition', 'must be created before data can be written') and lists server-side mutation failures such as 3176 locked, 3180 cannot_save, 3263 read_only_access, while annotations declare readOnlyHint=true. An agent reading these two sources gets contradictory expectations about whether state is modified. This is a direct annotation contradiction, so the dimension scores 1.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening sentences are front-loaded and efficient, and mentioning the webhook payload and response_json is valuable. However, roughly half the text is a flat twenty-item list of error codes that partly duplicates what the output schema and 'the call result explains each' already cover.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need not be explained, and the description does add the asynchronous webhook delivery model and the include_qbxml debug switch context. What remains missing is the state-changing nature of the call (permission requirements, whether the definition is editable afterwards), which matters for a creation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 80%, so most parameters are already documented in the schema, including owner_id, data_ext_type and the require flags. The description adds useful alias context (the qbXML `data_ext_def_add` wrapper is accepted) and the Customer/John Smith example, but no per-parameter semantics or defaults beyond what the schema already carries.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('adds a data extension definition to the specified object type') and clarifies with a concrete example (Customer / John Smith). The ordering rule ('must be created before data can be written to the data extension') implicitly separates it from create_data_ext, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the prerequisite sentence explaining that a definition must exist before extension data can be written, which gives the agent ordering context. There is no explicit statement of when to prefer update_data_ext_def or create_data_ext, and no note on prerequisites such as permissions for a private vs custom-field extension.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources