Conversion parameters

Every conversion accepts an optional set of parameters that tune how the input is parsed and how the output is generated. You can pass them two ways:

JSON — a URL-encoded params object: ?params={"dpi":300}
Dot notation — flat query parameters: ?dpi=300&label.width=4

If both are present, they’re merged and dot-notation values win. Most HTTP clients let you set query parameters without hand-encoding the URL.

# JSON style (URL-encode the value in practice)
POST /api/v2/convert/pdf/to/zpl?params={"label":{"width":4}}

# Dot-notation style
POST /api/v2/convert/pdf/to/zpl?label.width=4

Parameter reference

Parameter	Type	Default	Description
`label.width`	number (inches)	source-defined	Override the output label width
`label.height`	number (inches)	source-defined	Override the output label height
`dpi`	integer	`203`	Print density in dots per inch (e.g. `152`, `203`, `300`, `600`)
`rotation`	integer (degrees)	`0`	Rotate the output; must be a multiple of `90`
`scaling`	number (percent)	`100`	Scale the output up or down
`colorMode`	`BW` \| `GRAYSCALE` \| `COLOR`	`GRAYSCALE`	How color is handled in image/ZPL output
`darkness`	integer (0–100)	`70`	Threshold when reducing color → grayscale, or grayscale → 2-color
`position.x`	integer (pixels)	`0`	Horizontal offset of the top-left extraction corner
`position.y`	integer (pixels)	`0`	Vertical offset of the top-left extraction corner
`data`	JSON array	—	Values used to fill variable fields — see below
`dialect`	string	—	Output dialect, e.g. `moca` (paid)
`watermark`	boolean	`false`	Force a watermark on the output
`pdf.conversionMode`	`IMAGE` \| `NATIVE`	`IMAGE`	How a PDF source is converted — see PDF options
`pdf.pageNumber`	integer (0-based)	all pages	Convert a single PDF page instead of all pages
`zpl.imageCompression`	`Z64` \| `COMPRESSED_HEX`	`Z64`	Image compression when writing ZPL output
`zpl.commandsToIgnore`	array of strings	`[]`	ZPL commands the parser should skip, e.g. `["^PQ"]`

Filling variable data

Barcode and text fields on a label are often variable — placeholders that get real values at print time. Pass a data array to fill them; each array entry produces one label in the output.

curl -X POST "https://api.labelzoom.com/api/v2/convert/zpl/to/pdf" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/plain" \
  --data-binary @template.zpl \
  --get --data-urlencode 'params={"data":[{"sku":"A-100"},{"sku":"A-101"}]}' \
  --output labels.pdf

The example above renders the same template twice — one page per data entry. See Multi-label jobs for how multi-label output behaves per target format and plan.

Output tuning

dpi — thermal printers are commonly 203 dpi (8 dots/mm); 300 and 600 dpi produce sharper, larger rasters. Match the DPI of the printer you’ll send to.
rotation — only multiples of 90 are allowed; anything else returns 400.
scaling — a percentage; 50 halves the output size, 200 doubles it.
colorMode — BW is 2-color (pure black/white), GRAYSCALE dithers to simulate gray, COLOR keeps full color for image targets.
darkness — the luminance threshold applied when flattening color or grayscale down to fewer colors. Raise it to darken thin lines and small text.
position — a pixel offset for image extraction, letting you crop or reposition the source within the output canvas.

PDF options

When the source is a PDF:

pdf.conversionMode — IMAGE (default) rasterizes each page, which preserves the exact appearance of scanned or graphic-heavy PDFs. NATIVE extracts the underlying vector and text content.
pdf.pageNumber — a 0-based index to convert one page. Omit it to convert every page.

ZPL options

When the target is ZPL:

zpl.imageCompression — Z64 (default) is compact zlib-compressed, base64-encoded data. COMPRESSED_HEX is a more widely compatible fallback for older firmware.
zpl.commandsToIgnore — a list of ZPL commands to drop while parsing, for example ["^PQ"] to strip the print-quantity command.

Limits and validation

rotation must be a multiple of 90.
A ^PQ (print quantity) value above 1000 is rejected.
The maximum rasterizable label area is 15 in × 15 in at 203 dpi; larger labels return 400.
On the free tier, the request body is capped at 1 MB — see Rate limits and plans.