PayFlow API Documentation

Overview

The PayFlow API allows you to programmatically manage payroll operations, employee data, and compensation workflows. This RESTful API uses JSON for requests and responses, making it simple to integrate payroll functionality into your existing systems.

Base URL: https://api.payflow.dev/v1

Authentication

PayFlow uses API keys to authenticate requests. Include your API key in the Authorization header of every request.

Authorization: Bearer your_api_key_here

Getting Your API Key

Log in to your PayFlow dashboard
Navigate to Settings → API Access
Click "Generate New Key"
Store your key securely—it won't be shown again

Security Note: Never expose your API key in client-side code or public repositories. Treat it like a password.

Rate Limiting

API requests are limited to 1,000 calls per hour per API key. Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per hour
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Timestamp when the rate limit resets

Core Resources

Employees

Create, update, and retrieve employee information including compensation details, tax information, and payment preferences.

Payroll Runs

Initiate and manage payroll processing cycles, including calculating wages, deductions, and tax withholdings.

Payment Methods

Manage direct deposit accounts, payment cards, and other disbursement methods for employees.

Common Endpoints

Create Employee

Add a new employee to your payroll system.

Endpoint: POST /employees

Request Body:

{
  "first_name": "Sarah",
  "last_name": "Chen",
  "email": "sarah.chen@company.com",
  "employee_id": "EMP-2024-0156",
  "hire_date": "2024-01-15",
  "compensation": {
    "type": "salary",
    "amount": 75000,
    "currency": "USD",
    "pay_frequency": "biweekly"
  },
  "tax_details": {
    "filing_status": "single",
    "allowances": 1,
    "additional_withholding": 0
  }
}

Response (201 Created):

{
  "id": "emp_1a2b3c4d5e6f",
  "first_name": "Sarah",
  "last_name": "Chen",
  "email": "sarah.chen@company.com",
  "employee_id": "EMP-2024-0156",
  "status": "active",
  "hire_date": "2024-01-15",
  "created_at": "2024-01-15T14:30:00Z",
  "compensation": {
    "type": "salary",
    "amount": 75000,
    "currency": "USD",
    "pay_frequency": "biweekly"
  }
}

Example (Python):

import requests

url = "https://api.payflow.dev/v1/employees"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
data = {
    "first_name": "Sarah",
    "last_name": "Chen",
    "email": "sarah.chen@company.com",
    "employee_id": "EMP-2024-0156",
    "hire_date": "2024-01-15",
    "compensation": {
        "type": "salary",
        "amount": 75000,
        "currency": "USD",
        "pay_frequency": "biweekly"
    }
}

response = requests.post(url, json=data, headers=headers)
employee = response.json()
print(f"Created employee: {employee['id']}")

Example (JavaScript):

const createEmployee = async () => {
  const response = await fetch('https://api.payflow.dev/v1/employees', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: 'Sarah',
      last_name: 'Chen',
      email: 'sarah.chen@company.com',
      employee_id: 'EMP-2024-0156',
      hire_date: '2024-01-15',
      compensation: {
        type: 'salary',
        amount: 75000,
        currency: 'USD',
        pay_frequency: 'biweekly'
      }
    })
  });
  
  const employee = await response.json();
  console.log('Created employee:', employee.id);
};

Run Payroll

Process payroll for a specified pay period.

Endpoint: POST /payroll-runs

Request Body:

{
  "pay_period_start": "2024-01-01",
  "pay_period_end": "2024-01-15",
  "pay_date": "2024-01-19",
  "employee_ids": ["emp_1a2b3c4d5e6f", "emp_9z8y7x6w5v4u"],
  "auto_approve": false
}

Response (201 Created):

{
  "id": "pr_abc123xyz789",
  "status": "pending_review",
  "pay_period_start": "2024-01-01",
  "pay_period_end": "2024-01-15",
  "pay_date": "2024-01-19",
  "employee_count": 2,
  "total_gross_pay": 15234.50,
  "total_net_pay": 11456.78,
  "created_at": "2024-01-16T09:00:00Z"
}

Retrieve Employee

Get details for a specific employee.

Endpoint: GET /employees/{employee_id}

Response (200 OK):

{
  "id": "emp_1a2b3c4d5e6f",
  "first_name": "Sarah",
  "last_name": "Chen",
  "email": "sarah.chen@company.com",
  "status": "active",
  "hire_date": "2024-01-15",
  "compensation": {
    "type": "salary",
    "amount": 75000,
    "currency": "USD",
    "pay_frequency": "biweekly"
  },
  "payment_method": {
    "type": "direct_deposit",
    "bank_name": "First National Bank",
    "account_last4": "3456"
  }
}

Error Handling

PayFlow uses standard HTTP status codes and returns detailed error information in JSON format.

Common Status Codes

200 OK: Request succeeded
201 Created: Resource created successfully
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing API key
404 Not Found: Resource doesn't exist
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error (contact support)

Error Response Format

{
  "error": {
    "code": "invalid_employee_id",
    "message": "The employee_id field must be unique",
    "param": "employee_id",
    "type": "validation_error"
  }
}

Handling Errors

Python Example:

try:
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    employee = response.json()
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    print(f"Error: {error_data['error']['message']}")

JavaScript Example:

try {
  const response = await fetch(url, options);
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }
  const employee = await response.json();
} catch (error) {
  console.error('Failed to create employee:', error.message);
}

Webhooks

PayFlow can send real-time notifications to your application when events occur.

Available Events

payroll_run.completed: Payroll processing finished
employee.created: New employee added
employee.updated: Employee information changed
payment.failed: Payment couldn't be processed

Webhook Setup

Go to Settings → Webhooks in your dashboard
Add your endpoint URL
Select the events you want to receive
Save and verify the webhook

Webhook Payload Example

{
  "event": "payroll_run.completed",
  "timestamp": "2024-01-19T16:45:00Z",
  "data": {
    "payroll_run_id": "pr_abc123xyz789",
    "pay_date": "2024-01-19",
    "employee_count": 156,
    "total_net_pay": 234567.89,
    "status": "completed"
  }
}

Testing

Use our sandbox environment to test your integration without affecting live data.

Sandbox Base URL: https://sandbox.payflow.dev/v1

Test API Key

Request a sandbox API key from your dashboard to access the testing environment.
Sandbox data resets every 24 hours.

Support

Need help? We're here for you:

Documentation: docs.payflow.dev
Email: api-support@payflow.dev
Status Page: status.payflow.dev

Changelog

v1.2.0 (December 2024)

Added support for international payment methods
New endpoint for bulk employee updates
Improved error messages for tax calculation failures

v1.1.0 (October 2024)

Introduced webhook notifications
Added filtering options for payroll run queries
Performance improvements for large employee lists

API Documentation Sample