API Quick Start

1. Create an API key

Open API Key Settings. A signed-in account can start a one-time 7-day trial and receives a Trial Key automatically. Business accounts can create and keep up to five active keys.

Keep the key in a server-side secret manager or environment variable. Never put it in browser JavaScript, public source code, or a mobile application bundle.

For this example, set the key in your terminal:

export SHEETS_TO_LABELS_API_KEY="sk-your-api-key"

Open the Label Designer while signed in and design one label or card. Select Save Template, wait for the Cloud synced message, then copy the custom-... Template ID. You can retrieve it later from API Templates in API Key Settings.

3. Generate a PDF

The examples below send the same one-record request. layout.type: "single" makes the template dimensions the PDF page dimensions. Add more elements to records when you want a multi-page PDF with one item per page. For label sheets, use a supported preset; use manual only for stock whose exact paper, grid, margins, and gaps you know. See Choose a Print Layout for a side-by-side comparison and examples.

cURL

http_code=$(curl --silent --show-error \
  -X POST https://sheetstolabels.com/api/v1/generate-pdf \
  -H "Authorization: Bearer $SHEETS_TO_LABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quick-start-ag193-v1" \
  -H "X-Integration-Source: quick-start" \
  -d '{
    "templateId": "custom-1234567890",
    "layout": { "type": "single" },
    "records": [
      {
        "variables": {
          "code": "ag193",
          "qrUrl": "https://example.com/ag193",
          "name": "Test Ambassador"
        }
      }
    ]
  }' \
  --output api-response.bin \
  --write-out "%{http_code}")

if [ "$http_code" = "200" ]; then
  mv api-response.bin card-ag193.pdf
  echo "Saved card-ag193.pdf"
else
  jq . api-response.bin
fi

JavaScript (Node.js 18+)

import { writeFile } from 'node:fs/promises';

const response = await fetch('https://sheetstolabels.com/api/v1/generate-pdf', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SHEETS_TO_LABELS_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'quick-start-ag193-v1',
    'X-Integration-Source': 'quick-start',
  },
  body: JSON.stringify({
    templateId: 'custom-1234567890',
    layout: { type: 'single' },
    records: [
      {
        variables: {
          code: 'ag193',
          qrUrl: 'https://example.com/ag193',
          name: 'Test Ambassador',
        },
      },
    ],
  }),
});

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.code}: ${problem.detail}`);
}

await writeFile('card-ag193.pdf', Buffer.from(await response.arrayBuffer()));

Python

Install the Requests package first with python -m pip install requests.

import os
from pathlib import Path

import requests

response = requests.post(
    "https://sheetstolabels.com/api/v1/generate-pdf",
    headers={
        "Authorization": f"Bearer {os.environ['SHEETS_TO_LABELS_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": "quick-start-ag193-v1",
        "X-Integration-Source": "quick-start",
    },
    json={
        "templateId": "custom-1234567890",
        "layout": {"type": "single"},
        "records": [
            {
                "variables": {
                    "code": "ag193",
                    "qrUrl": "https://example.com/ag193",
                    "name": "Test Ambassador",
                }
            }
        ],
    },
    timeout=60,
)

if not response.ok:
    problem = response.json()
    raise RuntimeError(f"{problem.get('code')}: {problem.get('detail')}")

Path("card-ag193.pdf").write_bytes(response.content)

Java (Java 17+)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class GeneratePdf {
  public static void main(String[] args) throws Exception {
    String json = """
        {
          "templateId": "custom-1234567890",
          "layout": { "type": "single" },
          "records": [
            {
              "variables": {
                "code": "ag193",
                "qrUrl": "https://example.com/ag193",
                "name": "Test Ambassador"
              }
            }
          ]
        }
        """;

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://sheetstolabels.com/api/v1/generate-pdf"))
        .header(
            "Authorization",
            "Bearer " + System.getenv("SHEETS_TO_LABELS_API_KEY"))
        .header("Content-Type", "application/json")
        .header("Idempotency-Key", "quick-start-ag193-v1")
        .header("X-Integration-Source", "quick-start")
        .POST(HttpRequest.BodyPublishers.ofString(json))
        .build();

    HttpResponse<byte[]> response = HttpClient.newHttpClient().send(
        request,
        HttpResponse.BodyHandlers.ofByteArray());

    if (response.statusCode() != 200) {
      String problem = new String(response.body(), StandardCharsets.UTF_8);
      throw new RuntimeException(problem);
    }

    Files.write(Path.of("card-ag193.pdf"), response.body());
  }
}

A successful response has HTTP status 200 and Content-Type: application/pdf. Errors use application/problem+json, so this example checks the status before naming the response as a PDF. If jq is not installed, open api-response.bin as a text file to read the error.

Every request uses the same records array. Add more records when you want one combined batch PDF. Trial Keys can complete 10 successful single-page requests and do not consume Credits. Business keys consume 1 Credit per generated PDF page and support normal production use.

Before hard-coding IDs in a connector, use GET /api/v1/templates to list cloud templates and GET /api/v1/layout-presets to list supported label sheets. Continue with Automation Integrations for Google Sheets, Airtable, Make, n8n, and PrintNode workflows.

4. Use the request ID when you need help

Every response includes an X-Request-Id header. Error responses also include requestId in the JSON body. Include that value when contacting technical support.