REST API Reference

Overview

The Mergram REST API lets you trigger PDF merges and email campaigns programmatically. All endpoints use JSON for request and response bodies.

• Base URL — https://mergram.com/api/v1 (or your self-hosted domain)
• Content type — application/json
• Authentication — API keys via Authorization: Bearer <key> header

Authentication

All API requests require an API key. Include it in the Authorization header:

GET /api/v1/templates HTTP/1.1
Host: mergram.com
Authorization: Bearer mg_abc123...
Content-Type: application/json

Endpoints

List Templates

GET /api/v1/templates?search=&limit=50&offset=0

Returns a paginated list of your team’s templates.

Query parameters:

Get Template

GET /api/v1/templates/:id

Returns template metadata including column headers and required fields. Canvas data and form mapping are not included in the API response — use the visual editor to view or edit template layout.

Create Merge Job

POST /api/v1/merge

Request body:

{
  "templateId": "abc123-def456",
  "data": [
    { "Name": "Alice Chen", "InvoiceNumber": "INV-001", "Amount": "$2,700.00" },
    { "Name": "Bob Martinez", "InvoiceNumber": "INV-002", "Amount": "$5,400.00" }
  ],
  "outputConfig": {
    "combinePdf": false,
    "filenameTemplate": "Invoice_[[InvoiceNumber]]"
  }
}

Response (201 Created):

{
  "jobId": "abc123-def456-789",
  "status": "pending",
  "total": 2,
  "message": "Merge job enqueued. 2 rows will be processed."
}

Create Email Job

POST /api/v1/email

Request body:

{
  "templateId": "abc123-def456",
  "data": [
    { "Name": "Alice Chen", "Email": "alice@acme.com", "InvoiceNumber": "INV-001" },
    { "Name": "Bob Martinez", "Email": "bob@globex.com", "InvoiceNumber": "INV-002" }
  ],
  "email": {
    "toColumn": "Email",
    "subjectTemplate": "Your Invoice [[InvoiceNumber]]",
    "bodyTemplate": "<p>Dear [[Name]],</p><p>Please find your invoice attached.</p>"
  },
  "outputConfig": {
    "filenameTemplate": "Invoice_[[InvoiceNumber]]"
  }
}

Response (201 Created):

{
  "jobId": "abc123-def456-789",
  "status": "pending",
  "total": 2,
  "message": "Email job enqueued. 2 emails will be processed."
}

Get Job Status

GET /api/v1/jobs/:id

Returns the current status, progress, and any error details for a job.

Response:

{
  "id": "abc123-def456-789",
  "type": "pdf_merge",
  "status": "running",
  "total": 150,
  "completed": 75,
  "failed": 0,
  "createdAt": "2025-01-28T10:30:00Z"
}

Get Job Output

GET /api/v1/jobs/:id/output

Returns a list of generated files with download URLs. Only available when status is completed.

Response:

{
  "files": [
    {
      "filename": "Invoice_INV-001.pdf",
      "downloadUrl": "https://mergram.com/api/v1/files/...",
      "size": 245678
    }
  ]
}

Job Lifecycle

1. Submit — POST /api/v1/merge or POST /api/v1/email returns a jobId
2. Poll — GET /api/v1/jobs/:id to check status (pending, running, completed, failed)
3. Download — GET /api/v1/jobs/:id/output to get result file URLs

Error Handling

Best Practices

• Use environment variables — Store API keys in environment variables, never in source code
• Implement retry logic — Retry failed requests with exponential backoff (start with 2 seconds)
• Poll efficiently — Check job status every 2–5 seconds, not more frequently
• Validate before submitting — Verify template IDs exist before creating jobs
• Monitor credit usage — Check your credit balance periodically to avoid 402 errors mid-workflow

Limitations

• No template creation via API — Templates must be created in the visual editor
• No file upload via API — PDF templates and spreadsheets must be uploaded through the web interface
• Polling only — No webhook callbacks for job completion notifications
• Rate limited — Standard rate limits apply (100 total requests per minute, 20 write operations per minute)
• Inline data limit — API requests accept up to 10,000 rows of inline data per job. For larger datasets, use the web interface which supports up to 100,000 rows