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" \
  -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',
  },
  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",
    },
    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")
        .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.

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.