Quickstart

Upload a payroll PDF and extract structured data in five steps.

Prerequisites

A Parsify account with an API key
A payroll PDF document to process

Step 1: Get an API Key

Create an API key from the Parsify Dashboard under Settings → API Keys. Make sure your key has the following scopes:

documents:write
jobs:read
jobs:write

Step 2: Upload a Payroll PDF

Upload your document to Parsify. The API accepts PDF files up to 25 MB.

curl -X POST https://api.parsifyhq.com/api/v1/documents/upload/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@payroll_journal.pdf"

import requests
 
response = requests.post(
    "https://api.parsifyhq.com/api/v1/documents/upload/",
    headers={"X-API-Key": "YOUR_API_KEY"},
    files={"file": open("payroll_journal.pdf", "rb")},
)
document = response.json()
print(document["id"])

const formData = new FormData();
formData.append("file", fs.createReadStream("payroll_journal.pdf"));
 
const response = await fetch(
  "https://api.parsifyhq.com/api/v1/documents/upload/",
  {
    method: "POST",
    headers: { "X-API-Key": "YOUR_API_KEY" },
    body: formData,
  }
);
const document = await response.json();
console.log(document.id);

The response includes the document ID you’ll use in the next step:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "filename": "payroll_journal.pdf",
  "status": "uploaded",
  "created_at": "2026-03-16T12:00:00Z"
}

Step 3: Create an Extraction Job

Create a job to extract structured payroll data from the uploaded document.

curl -X POST https://api.parsifyhq.com/api/v1/jobs/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"}'

response = requests.post(
    "https://api.parsifyhq.com/api/v1/jobs/",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"document_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab"},
)
job = response.json()
print(job["id"])

const response = await fetch("https://api.parsifyhq.com/api/v1/jobs/", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    document_id: "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  }),
});
const job = await response.json();
console.log(job.id);

{
  "id": "e5f6a7b8-1234-56cd-ef78-9012345678ab",
  "document_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "pending",
  "created_at": "2026-03-16T12:00:05Z"
}

Step 4: Poll for Completion

Extraction jobs run asynchronously. Poll the job endpoint until the status changes to completed.

curl https://api.parsifyhq.com/api/v1/jobs/e5f6a7b8-1234-56cd-ef78-9012345678ab/ \
  -H "X-API-Key: YOUR_API_KEY"

import time
 
job_id = "e5f6a7b8-1234-56cd-ef78-9012345678ab"
 
while True:
    response = requests.get(
        f"https://api.parsifyhq.com/api/v1/jobs/{job_id}/",
        headers={"X-API-Key": "YOUR_API_KEY"},
    )
    job = response.json()
 
    if job["status"] == "completed":
        print("Extraction complete!")
        break
    elif job["status"] == "failed":
        print("Extraction failed:", job.get("error"))
        break
 
    time.sleep(2)

const jobId = "e5f6a7b8-1234-56cd-ef78-9012345678ab";
 
const poll = async () => {
  while (true) {
    const response = await fetch(
      `https://api.parsifyhq.com/api/v1/jobs/${jobId}/`,
      { headers: { "X-API-Key": "YOUR_API_KEY" } }
    );
    const job = await response.json();
 
    if (job.status === "completed") {
      console.log("Extraction complete!");
      return job;
    } else if (job.status === "failed") {
      throw new Error(`Extraction failed: ${job.error}`);
    }
 
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
};
 
const completedJob = await poll();

Step 5: Read the Canonical Output

Once the job is complete, the response includes the extraction result with structured, normalized payroll data and confidence scores.

{
  "id": "e5f6a7b8-1234-56cd-ef78-9012345678ab",
  "status": "completed",
  "result": {
    "confidence": 0.97,
    "payroll_data": {
      "pay_period": {
        "start_date": "2026-03-01",
        "end_date": "2026-03-15"
      },
      "employees": [
        {
          "name": "Jane Smith",
          "gross_pay": 5250.00,
          "net_pay": 3847.50,
          "deductions": {
            "federal_tax": 787.50,
            "state_tax": 262.50,
            "health_insurance": 175.00,
            "retirement_401k": 177.50
          }
        }
      ],
      "totals": {
        "gross_pay": 5250.00,
        "net_pay": 3847.50,
        "total_deductions": 1402.50
      }
    }
  }
}

The canonical output follows a consistent schema regardless of which payroll provider generated the original document, making it straightforward to compare data across providers during a migration.

Next Steps

Authentication — Learn about API key scopes and best practices
API Reference — Explore the full API

Introduction Authentication