📄 CSVLink Invoice/Template API

Welcome to the CSVLink API. This documentation provides a complete guide to programmatically generate PDFs and other image formats from your saved templates.

Getting Started

API Key & Access

Pro Subscription Required: Access to the API is available exclusively for users on the Pro plan.

To authenticate your requests, you will need an API key. You can generate one from your account settings:

Navigate to your Settings page on the CSVLink editor.
Find the "API Key" section.
If you don't have a key, click "Generate API Key".
Copy your key and store it in a secure location.

🔑 Authentication

All requests must include your API key in the Authorization header as a Bearer token.

Authorization: Bearer <your_api_key>

Important: Your API key provides full access to your account's API capabilities. Keep it secret and never expose it in client-side JavaScript. All API calls should be made from a secure backend server.

🚀 Endpoints

Generate a PDF

This endpoint generates a document (PDF, PNG, or JPG) from a saved template and dynamic data.

POST /api/generate

Request Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <api_key>`

Request Body

The body must be a JSON object containing the template ID, data, and optional settings.

{
  "templateId": "6dec5f4c-a31b-416e-acf5-9debb9e56906",
  "data": {
    "customerName": "Jane Smith",
    "invoiceNumber": "INV-002",
    "date": "2025-08-24",
    "amount": "250.00"
  },
  "options": {
    "format": "pdf",         // "pdf" | "png" | "jpg"
    "delivery": "download"   // "download" | "url"
  }
}

Response

Option A: Direct File Download (delivery: "download")

Returns the binary file stream. This is the default behavior.

200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice-INV-002.pdf"

(Binary file stream)

Option B: JSON with URL (delivery: "url")

Returns a JSON object with a link to the hosted file.

{
  "success": true,
  "url": "https://cdn.csvlink.app/files/invoice-INV-002.pdf",
  "message": "PDF generated successfully."
}

List Templates

Retrieve a list of your available templates.

GET /api/templates

Request Headers

Header	Value
`Authorization`	`Bearer <api_key>`

Response

Returns a JSON object containing an array of your templates.

{
  "templates": [
    {
      "id": "6dec5f4c-a31b-416e-acf5-9debb9e56906",
      "name": "Default Invoice",
      "description": "Basic invoice layout",
      "createdAt": "2025-08-20T12:00:00Z"
    }
  ]
}

⚠️ Error Handling

If a request fails, the API will respond with an appropriate HTTP status code and a standard JSON error body:

{
  "success": false,
  "error": "A human-readable error message."
}

Common HTTP Status Codes

Status Code	Meaning
`401 Unauthorized`	Missing or invalid API key.
`404 Not Found`	The specified template was not found.
`400 Bad Request`	Missing or invalid fields in the request body.
`500 Internal Server Error`	An unexpected error occurred on the server.

💻 Integration Examples

Node.js

import fetch from "node-fetch";
import fs from "fs";

async function generateInvoice() {
  const response = await fetch("https://www.csvlink.app/api/generate", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_KEY"
    },
    body: JSON.stringify({
      templateId: "6dec5f4c-a31b-416e-acf5-9debb9e56906",
      data: { customerName: "Jane Smith", invoiceNumber: "INV-002" }
    })
  });

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

  const buffer = await response.arrayBuffer();
  fs.writeFileSync("invoice.pdf", Buffer.from(buffer));
  console.log("Invoice saved to invoice.pdf");
}

generateInvoice().catch(console.error);

Python

import requests

api_key = "YOUR_API_KEY"
api_url = "https://www.csvlink.app/api/generate"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "templateId": "6dec5f4c-a31b-416e-acf5-9debb9e56906",
    "data": {
        "customerName": "Jane Smith",
        "invoiceNumber": "INV-002"
    }
}

try:
    res = requests.post(api_url, headers=headers, json=payload)
    res.raise_for_status() # Raises an exception for 4xx/5xx errors

    with open("invoice.pdf", "wb") as f:
        f.write(res.content)
    print("Invoice saved to invoice.pdf")

except requests.exceptions.HTTPError as err:
    print(f"HTTP Error: {err.response.status_code} - {err.response.text}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

3. Get Template Data

Fetches the raw JSON data for a specific template. This is useful for inspecting a template's structure or dynamically building a user interface based on its fields.

POST /api/get-template

Request Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <api_key>`

Request Body

{
                "templateId": "6dec5f4c-a31b-416e-acf5-9debb9e56906"
}

Successful Response (200 OK)

Returns a JSON object containing the complete data structure of the requested template.

{
                "success": true,
                "template": {
                    "name": "Default Invoice",
                    "layout": { "...": "..." },
                    "fields": [
                        { "name": "customerName", "type": "text" }
                    ]
                }
}

Error Responses

This endpoint returns specific error codes based on the validation outcome:

Status Code	Reason
`400 Bad Request`	The `templateId` field is missing from the request body.
`401 Unauthorized`	The `Authorization` header is missing.
`403 Forbidden`	The provided API Key is invalid or does not have permission.
`404 Not Found`	The template does not exist or does not belong to your account.
`405 Method Not Allowed`	The request used a method other than POST.