API and Pipelines

XL Docs has an API endpoint for callers with no browser window, such as Quickbase Pipelines or your own integrations. It takes the same parameters as a button, creates the document the same way, and returns either the file itself or a JSON result.

Replace https://... with your designated XL Docs server URL, created by the installation wizard.

Parameters

Send the parameters in the query string, joined with &, exactly as in a button formula. See Formula URL parameters. The request body isn't read—don't send the parameters as JSON or as form fields. As an alternative, Base64-encode the whole parameter string and send it as a single request parameter: ?request=<Base64 string>.

• The required parameters are the same as for a button: clientid, appid, dbid, tpdbid, tpid, fn, and exactly one of msid or msqry. To find your Client ID and the app, table, and field IDs, see Find your Client ID, table IDs, and field IDs.

• Add stream=y to get the file back in the response. Without it, the document is only saved to the storage you specify (for example faid, a repository table, Amazon S3, or Dropbox). See Output and storage.

• With msqry, an API request creates up to 50 documents by default; your account's limit may differ. Use batch processing for more.

• preqbaction isn't run by the API. If you need to update the record first, do it in an earlier step (for example a Quickbase Pipelines Update Record step) before you call XL Docs.

Authentication

If your account uses Quickbase enhanced security, send a Quickbase user token in the Authorization header, in the same format as the Quickbase REST API:

Authorization: QB-USER-TOKEN <your user token>

The token is used to confirm that its user has access to the record (or the records matched by msqry). Use a token for a user with access to the master table and to the fields and tables the document is saved to. See Enhanced security overview. If your app requires application tokens, also pass apptoken in the query string.

Response

The API always answers with HTTP 200—even when the request fails—so check the response body, not the status code.

• success—true if the document was created and saved. Use this to decide whether the request worked.

• errors—the reason the request failed. Missing or malformed parameters return Invalid parameters. Other failures return the same message a button would show, for example:

{ "success": false, "errors": ["The template record was not found. Please make sure that the tpid parameter field is correct."] }

When you ask for a file, tell a file from an error by the content type: JSON means the request failed. Messages are listed in XL Docs messages and troubleshooting.

Examples

Create a PDF from template 2 for record 42 and save it in file attachment field 51:

curl -X POST "https://.../api/generate?clientid=Q#&appid=<app id>&dbid=<table id>&msid=42&tpdbid=<templates table id>&tpid=2&fn=Invoice&docfmt=pdf&faid=51" \
  -H "Authorization: QB-USER-TOKEN <your user token>"

Create the same PDF and download it to a local file:

curl -X POST "https://.../api/generate?clientid=Q#&appid=<app id>&dbid=<table id>&msid=42&tpdbid=<templates table id>&tpid=2&fn=Invoice&docfmt=pdf&stream=y" \
  -H "Authorization: QB-USER-TOKEN <your user token>" \
  -o Invoice_42.pdf

Create a CSV export of record 42 and download it:

curl -X POST "https://.../api/generate?clientid=Q#&appid=<app id>&dbid=<table id>&msid=42&tpdbid=<templates table id>&tpid=5&fn=Export&fnrid=N&docfmt=csv&stream=y" \
  -H "Authorization: QB-USER-TOKEN <your user token>" \
  -o Export.csv

Create one workbook with a tab for every record whose field 10 is Active, and download it (the query is URL-encoded):

curl -X POST "https://.../api/generate?clientid=Q#&appid=<app id>&dbid=<table id>&msqry=%7B'10'.EX.'Active'%7D&sameworkbook=y&tpdbid=<templates table id>&tpid=5&fn=Active_Records&fnrid=N&docfmt=xlsx&stream=y" \
  -H "Authorization: QB-USER-TOKEN <your user token>" \
  -o Active_Records.xlsx

Create a document for each related record and save each one on its record (no file in the response):

curl -X POST "https://.../api/generate?clientid=Q#&appid=<app id>&dbid=<table id>&msqry=%7B'6'.EX.'7'%7D&tpdbid=<templates table id>&tpid=36&fn=Expenses&docfmt=xlsx&faid=62&xlddte=63" \
  -H "Authorization: QB-USER-TOKEN <your user token>"

Use in Quickbase Pipelines

Pipelines usually work best when XL Docs saves the document to Quickbase (or cloud storage) and returns a JSON result, so leave stream out.

1. Add a step that sends an HTTP request—for example, the Webhooks channel's Make Request step.

2. Set the method to POST and the URL to the endpoint with your parameters. Use data from earlier steps for values such as the Record ID#—for example, msid={{a.id}}.

3. Add the header Authorization with the value QB-USER-TOKEN followed by your user token.

4. Leave the request body empty—parameters go in the URL.

5. Optionally, add a condition after the request that checks the response's success value, and log or notify on anything in errors.

Differences from a button

• No progress window or error page—results come back in the response.

• A streamed PDF is returned directly as the file, not opened in a browser preview.

• The user token in the Authorization header takes the place of the temporary token a button sends.

• preqbaction isn't run.

Questions? Submit a technical support case.