API Guide

1. What the API does

Every time someone on your team fills in a form in Straight2PDF, we store their answers and create a PDF. Normally you look at these on the Submissions page. The API lets another program — your job management system, CRM, accounts software, a shared drive, or a simple script — fetch them automatically, so nobody has to download and re-type anything.

In plain terms, your program asks us “anything new since last time?” and we hand over each new submission: who sent it, when, every answer, and the PDF itself.

2. Before you start

• You need the Pro plan and the API access add-on (£10/month + VAT). The account owner turns it on in the admin area under Settings → Billing → Add-ons → Add API access.
• Copy your username and password straight away. They are shown once, just after you add the add-on (or reset them). We only store a scrambled copy of the password, so we can't show it again — if it's lost, use Reset username & password on the Billing page to get a new one.
• Your username looks like s2p_ followed by 16 letters and numbers. The password is 32 characters. Both are generated for you so they are always strong.
• Only your company's submissions are ever returned — your login is tied to your company.
• If someone else (a developer or IT company) is setting this up, send them a link to this page and give them the username and password securely (not in the same email as the link, and never in a shared spreadsheet).

3. Quick start: your first test in 5 minutes

You can check your login works without any programming, using your web browser.

1. Open this address in your browser:
   https://api.straight2pdf.co.uk/v1/new-submissions/?peek=1&limit=1
2. Your browser asks for a username and password. Paste in the ones from the Billing page.
3. You'll see some text starting with {"submissions":[. That's the oldest submission you haven't collected yet (on your first test, your very first submission), in JSON — a standard format programs understand. (If you have no submissions yet, you'll see "submissions":[] — send a test form from the app and try again.)

Prefer a command line? On Windows 10/11, macOS or Linux, the same test is:

curl -u "YOUR_USERNAME:YOUR_PASSWORD" "https://api.straight2pdf.co.uk/v1/new-submissions/?peek=1&limit=1"

On Windows, run this in Command Prompt, or type curl.exe instead of curl in PowerShell.

4. How collecting new submissions works

Think of it like a bookmark. We remember the last submission we gave you. Each time your program asks for new submissions:

1. we send the next batch after the bookmark (oldest first, up to 20 at a time),
2. then move the bookmark past them, so they aren't sent again.

If the reply says "has_more": true, there are more waiting — ask again straight away until it says false. Then wait a while (for example 15 minutes) and ask again. The examples below do all of this for you.

5. The two API addresses

Every request uses HTTPS, the GET method, and your username and password (see Basic authentication). Replies are JSON.

New submissions

GET https://api.straight2pdf.co.uk/v1/new-submissions/

One submission

GET https://api.straight2pdf.co.uk/v1/submission/?id=123

Returns a single submission by its ID — useful to fetch one again, or to look up a submission someone mentions. You'll find a submission's ID on its page in the admin area (Submission ID at the top) and in every API reply. It doesn't move the bookmark.

curl -u "YOUR_USERNAME:YOUR_PASSWORD" "https://api.straight2pdf.co.uk/v1/submission/?id=123"

You'll get a “not found” reply if the ID doesn't exist, belongs to another company, was deleted, or is older than your plan's submission history.

6. What you get back

A reply from new-submissions looks like this (the PDF is shortened here):

{
  "submissions": [
    {
      "submission_id": 1042,
      "form_id": 57,
      "form_name": "Site Inspection",
      "submitted_at": "2026-09-28T14:05:12+01:00",
      "status": "submitted",
      "submitted_by": { "name": "Sam Jones", "email": "sam@example.co.uk", "guest": false },
      "answers": [
        { "field": "site_name", "label": "Site name", "value": "Unit 4, Mill Lane" },
        { "field": "inspection_date", "label": "Inspection date", "value": "28/09/2026" },
        { "field": "passed", "label": "Passed?", "value": "Yes" },
        { "field": "_gps_submit", "label": "Submit location", "value": "51.5072,-0.1276" }
      ],
      "pdf": {
        "filename": "submission_1042.pdf",
        "content_type": "application/pdf",
        "content_base64": "JVBERi0xLjcKJcOkw7zDtsOf... (the whole PDF)"
      }
    }
  ],
  "cursor": 1042,
  "has_more": false,
  "waiting_for_processing": false,
  "peek": false
}

The submission address returns {"submission": { ... }} with the same fields for one submission.

7. Ready-to-use examples

Each example collects everything new and saves every submission as a PDF and a .json file of its answers, then stops. Replace YOUR_USERNAME and YOUR_PASSWORD with your login. Run it on a schedule (see section 9) and new submissions keep arriving.

Windows PowerShell (no installing needed)

Save as collect-straight2pdf.ps1, then right-click → Run with PowerShell. Files are saved to C:\Straight2PDF Submissions.

# Collects new Straight2PDF submissions and saves each one as a PDF plus a
# .json file of its answers. Safe to run as often as you like.

$username = "YOUR_USERNAME"
$password = "YOUR_PASSWORD"
$saveTo   = "C:\Straight2PDF Submissions"

$pair    = "{0}:{1}" -f $username, $password
$headers = @{ Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair)) }
New-Item -ItemType Directory -Force -Path $saveTo | Out-Null

do {
    $result = Invoke-RestMethod -Uri "https://api.straight2pdf.co.uk/v1/new-submissions/?limit=20" -Headers $headers
    foreach ($s in $result.submissions) {
        $name = "submission_{0}" -f $s.submission_id
        if ($s.pdf) {
            [IO.File]::WriteAllBytes((Join-Path $saveTo "$name.pdf"), [Convert]::FromBase64String($s.pdf.content_base64))
        }
        $s | Select-Object -Property * -ExcludeProperty pdf | ConvertTo-Json -Depth 10 |
            Set-Content -Encoding UTF8 (Join-Path $saveTo "$name.json")
        Write-Host "Saved $name ($($s.form_name))"
    }
} while ($result.has_more)

Python

# Collects new Straight2PDF submissions and saves each one as a PDF plus a
# .json file of its answers. Needs: pip install requests
import base64, json, pathlib, requests

USERNAME = "YOUR_USERNAME"
PASSWORD = "YOUR_PASSWORD"
save_to = pathlib.Path("straight2pdf_submissions")
save_to.mkdir(exist_ok=True)

while True:
    response = requests.get(
        "https://api.straight2pdf.co.uk/v1/new-submissions/",
        params={"limit": 20},
        auth=(USERNAME, PASSWORD),
        timeout=120,
    )
    response.raise_for_status()
    data = response.json()

    for s in data["submissions"]:
        name = f"submission_{s['submission_id']}"
        if s["pdf"]:
            (save_to / f"{name}.pdf").write_bytes(base64.b64decode(s["pdf"]["content_base64"]))
        s.pop("pdf", None)
        (save_to / f"{name}.json").write_text(json.dumps(s, indent=2))
        print("Saved", name, s["form_name"])

    if not data["has_more"]:
        break

Node.js

Save as collect.mjs and run node collect.mjs.

// Collects new Straight2PDF submissions (Node.js 18 or newer, no packages needed).
import { writeFile, mkdir } from "node:fs/promises";

const USERNAME = "YOUR_USERNAME";
const PASSWORD = "YOUR_PASSWORD";
const auth = "Basic " + Buffer.from(`${USERNAME}:${PASSWORD}`).toString("base64");
await mkdir("straight2pdf_submissions", { recursive: true });

let data;
do {
  const response = await fetch("https://api.straight2pdf.co.uk/v1/new-submissions/?limit=20", {
    headers: { Authorization: auth },
  });
  if (!response.ok) throw new Error(`API error ${response.status}: ${await response.text()}`);
  data = await response.json();

  for (const s of data.submissions) {
    const name = `straight2pdf_submissions/submission_${s.submission_id}`;
    if (s.pdf) await writeFile(`${name}.pdf`, Buffer.from(s.pdf.content_base64, "base64"));
    const { pdf, ...answers } = s;
    await writeFile(`${name}.json`, JSON.stringify(answers, null, 2));
    console.log("Saved", name, s.form_name);
  }
} while (data.has_more);

PHP

<?php
// Collects new Straight2PDF submissions (PHP with the curl extension).
$username = 'YOUR_USERNAME';
$password = 'YOUR_PASSWORD';
$saveTo = __DIR__ . '/straight2pdf_submissions';
@mkdir($saveTo);

do {
    $ch = curl_init('https://api.straight2pdf.co.uk/v1/new-submissions/?limit=20');
    curl_setopt_array($ch, [
        CURLOPT_USERPWD => $username . ':' . $password,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 120,
    ]);
    $body = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status !== 200) {
        exit("API error $status: $body\n");
    }
    $data = json_decode($body, true);

    foreach ($data['submissions'] as $s) {
        $name = $saveTo . '/submission_' . $s['submission_id'];
        if ($s['pdf']) {
            file_put_contents($name . '.pdf', base64_decode($s['pdf']['content_base64']));
        }
        unset($s['pdf']);
        file_put_contents($name . '.json', json_encode($s, JSON_PRETTY_PRINT));
        echo "Saved {$name} ({$s['form_name']})\n";
    }
} while ($data['has_more']);

8. Without writing code (Power Automate and similar)

Any automation tool that can make an HTTP GET request with Basic authentication can use the API — for example Microsoft Power Automate, Make or Zapier (“Webhooks”). As an example, to save every new PDF to OneDrive or SharePoint with Power Automate:

1. Create a Scheduled cloud flow that repeats every 15 minutes.
2. Add an HTTP action: Method GET, URI https://api.straight2pdf.co.uk/v1/new-submissions/?limit=20, Authentication Basic, with your username and password. (The HTTP action needs a Power Automate premium licence.)
3. Add Parse JSON on the HTTP body, using the example reply in section 6 to “Generate from sample”.
4. Add Apply to each over submissions, and inside it Create file with File name submission_ + submission_id + .pdf and File content set to this expression:

base64ToBinary(items('Apply_to_each')?['pdf']?['content_base64'])

To catch busy periods, wrap steps 2–4 in a Do until that stops when has_more is false.

9. Running it automatically

Windows (Task Scheduler): open Task Scheduler → Create Basic Task → name it “Collect Straight2PDF submissions” → Trigger Daily → Action Start a program: Program powershell.exe, Arguments -ExecutionPolicy Bypass -File "C:\Scripts\collect-straight2pdf.ps1". Then open the task's properties → Triggers → Edit → tick Repeat task every 15 minutes for a duration of 1 day.

Linux or Mac (cron): run crontab -e and add a line like:

*/15 * * * * /usr/bin/python3 /home/you/collect_straight2pdf.py >> /home/you/straight2pdf.log 2>&1

Every 5–30 minutes is plenty. Checking more often than once a minute doesn't get submissions any faster and may hit the rate limit.

10. Error messages and what to do

Errors come back as JSON like {"error": "unauthorised", "message": "..."} with one of these HTTP status codes:

11. Keeping your login safe

• The API uses Basic authentication over HTTPS: your program sends the username and password with every request, encrypted in transit. Most tools have a “Basic auth” option; if you build the header yourself it is Authorization: Basic followed by username:password encoded in Base64, for example:

Authorization: Basic czJwX2FiYzEyMzpleGFtcGxlLXBhc3N3b3Jk

• Treat the password like a bank password: store it in your program's settings or a password manager, not in emails, chat messages or shared documents.
• HTTPS only. Requests to http:// are refused, never redirected, so a mistyped address fails straight away instead of sending your password unencrypted.
• Only the account owner can reset the login. If you think it has been seen by someone who shouldn't have it, reset it straight away on the Billing page — the old one stops working immediately — and put the new one into your program.
• Email alerts: the account owner(s) get an email whenever a new login is issued or reset, saying who did it, when and from where. If you didn't expect one, reset the login and change your own password.
• Allowed IP addresses (recommended): we can restrict your login to the address(es) your system connects from — single addresses or ranges such as 203.0.113.0/24. The login is then refused from anywhere else, so a leaked password is useless on its own. Contact us with the addresses (the recent activity list on the Billing page shows which one your system uses); the Billing page shows the current list. If your system's address changes (some home and cloud connections do), let us know or calls will fail with 403.
• Recent activity: the Billing page lists the last 20 API calls — when, from which address, which endpoint, whether it worked, and how many submissions were sent — including failed logins with your username. Calls are kept for 90 days.
• Removing the API access add-on turns the login off.

12. Troubleshooting and FAQs

I get an empty list, but I know there are submissions.

They've probably already been collected (the bookmark has moved past them) — perhaps by an earlier test without peek=1. Fetch them again with ?since_id=0 (everything) or ?since_id= a submission ID just before the ones you want.

A submission has "pdf": null.

That form doesn't produce a PDF (for example some HR forms), or the PDF couldn't be created. You still get all the answers. You can check the submission's page in the admin area.

Some older submissions aren't available.

The API follows your plan's submission history (6 months on Pro, 18 months on Business).

Can I send data into Straight2PDF, or change submissions?

Not at the moment — the API is read-only.

Can we have more than one login?

There's one login per company. If several systems need the data, collect it once and share it internally, or ask us.

Where's my username?

On the Billing page, under API access. The password is never shown again after it's issued — reset it to get a new one.

Still stuck?

Contact us with the time you made the request and the error message you saw (never send us your password).