Payroll API Documentation

API Overview

The BizFirstFi Payroll API provides comprehensive endpoints for managing payroll operations, employee data, tax calculations, and compliance reporting. All endpoints use RESTful conventions and return JSON responses.

RESTful Design

Standard HTTP methods and status codes for predictable API behavior

Secure Authentication

OAuth 2.0 and API key authentication with role-based access control

Comprehensive Documentation

Complete reference with examples, schemas, and interactive testing

API Information	Details
Base URL	https://api.bizfirstfi.com/v1/payroll
Authentication	OAuth 2.0 / API Key
Response Format	JSON
Rate Limit	1000 requests/hour

Authentication

OAuth 2.0 Authentication

The preferred method for authenticating with the Payroll API. Obtain access tokens using the client credentials flow.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=your_client_id
&client_secret=your_client_secret
&scope=payroll:read payroll:write
                

API Key Authentication

For server-to-server integrations, you can use API key authentication by including the key in the Authorization header.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
                

Employee Management

Employee Endpoints

Create Employee

POST /employees { "employee_number": "EMP001", "first_name": "John", "last_name": "Doe", "email": "[email protected]", "hire_date": "2025-01-15", "department": "Engineering", "position": "Software Developer", "compensation": { "type": "salary", "amount": 75000, "currency": "USD" } }

Get Employee

GET /employees/{employee_id}

Response:
{
  "id": "uuid",
  "employee_number": "EMP001",
  "first_name": "John",
  "last_name": "Doe",
  "status": "active",
  "hire_date": "2025-01-15",
  "compensation": {...},
  "benefits": {...}
}
                        

Update Employee

PUT /employees/{employee_id}
{
  "department": "Senior Engineering",
  "position": "Senior Software Developer",
  "compensation": {
    "type": "salary",
    "amount": 85000,
    "currency": "USD"
  }
}
                        

List Employees

GET /employees?limit=50&offset=0&status=active

Response:
{
  "employees": [...],
  "total": 150,
  "limit": 50,
  "offset": 0
}
                        

Payroll Processing

Payroll Run Endpoints

Create Payroll Run

POST /payroll-runs
{
  "pay_period_start": "2025-01-01",
  "pay_period_end": "2025-01-15",
  "pay_date": "2025-01-16",
  "description": "Bi-weekly payroll",
  "employees": ["emp1", "emp2"]
}
                        

Calculate Payroll

POST /payroll-runs/{run_id}/calculate

Response:
{
  "run_id": "uuid",
  "status": "calculated",
  "total_gross": 125000.00,
  "total_net": 97500.00,
  "entries": [...]
}
                        

Approve Payroll

POST /payroll-runs/{run_id}/approve
{
  "approved_by": "manager_id",
  "approval_notes": "Reviewed and approved"
}

Response:
{
  "status": "approved",
  "approved_at": "2025-01-16T09:00:00Z"
}
                        

Process Payment

POST /payroll-runs/{run_id}/process

Response:
{
  "status": "processed",
  "payment_method": "direct_deposit",
  "processed_at": "2025-01-16T12:00:00Z",
  "confirmation_number": "PAY123456"
}
                        

Time & Attendance

Timesheet Management

POST /timesheets/import
{
  "pay_period_start": "2025-01-01",
  "pay_period_end": "2025-01-15",
  "source": "external_system",
  "timesheets": [
    {
      "employee_id": "uuid",
      "regular_hours": 80.0,
      "overtime_hours": 5.0,
      "pto_hours": 8.0,
      "approved": true,
      "approved_by": "manager_uuid",
      "entries": [
        {
          "date": "2025-01-01",
          "clock_in": "09:00:00",
          "clock_out": "17:00:00",
          "break_minutes": 60,
          "hours_worked": 8.0
        }
      ]
    }
  ]
}
                

Time Tracking Endpoints

Endpoint	Method	Description	Auth Required
/timesheets	GET	List employee timesheets	Yes
/timesheets/import	POST	Import timesheet data	Yes
/timesheets/{id}/approve	POST	Approve timesheet	Yes
/time-off-requests	GET	List time-off requests	Yes

Tax Management

Tax Calculation

The API automatically calculates federal, state, and local taxes based on employee location and tax configuration.

POST /tax/calculate
{
  "employee_id": "uuid",
  "gross_pay": 2500.00,
  "pay_period": "bi-weekly",
  "ytd_gross": 15000.00,
  "tax_jurisdictions": ["federal", "ca_state", "sf_city"]
}

Response:
{
  "total_taxes": 625.00,
  "tax_breakdown": [
    {
      "jurisdiction": "federal",
      "tax_type": "income",
      "rate": 0.12,
      "taxable_amount": 2500.00,
      "tax_amount": 300.00
    },
    {
      "jurisdiction": "federal",
      "tax_type": "social_security",
      "rate": 0.062,
      "taxable_amount": 2500.00,
      "tax_amount": 155.00
    }
  ]
}
                

Tax Configuration

Supported Tax Types

Federal Income Tax
State Income Tax
Social Security (FICA)
Medicare Tax
State Unemployment (SUTA)
Local City/County Taxes

Tax Jurisdictions

All 50 US States
Washington D.C.
Major metropolitan areas
School district taxes
Special tax zones

Reporting

Standard Reports

Report Type	Endpoint	Format	Schedule
Payroll Summary	/reports/payroll-summary	JSON, PDF	Per pay period
Tax Liability	/reports/tax-liability	JSON, Excel	Monthly/Quarterly
Employee Earnings	/reports/employee-earnings	JSON, CSV	On-demand
Year-end Reports	/reports/year-end	PDF, CSV	Annual

Custom Report Generation

POST /reports/custom
{
  "report_type": "custom",
  "title": "Department Payroll Analysis",
  "date_range": {
    "start": "2025-01-01",
    "end": "2025-03-31"
  },
  "filters": {
    "departments": ["Engineering", "Sales"],
    "employee_status": "active"
  },
  "fields": [
    "employee_name",
    "department",
    "gross_pay",
    "net_pay",
    "taxes"
  ],
  "format": "excel"
}
                

Webhooks

Event Notifications

Subscribe to real-time notifications for payroll events using webhooks.

Available Events

payroll.run.created
payroll.run.calculated
payroll.run.approved
payroll.run.processed
employee.created
employee.updated
timesheet.submitted
payment.completed

Webhook Configuration

POST /webhooks
{
  "url": "https://yourapp.com/webhooks",
  "events": [
    "payroll.run.processed",
    "payment.completed"
  ],
  "secret": "your_webhook_secret"
}
                        

Error Handling

HTTP Status Codes

Status Code	Description	Common Causes
200 OK	Request successful	Standard success response
400 Bad Request	Invalid request data	Missing required fields, invalid format
401 Unauthorized	Authentication failed	Invalid API key or expired token
403 Forbidden	Access denied	Insufficient permissions
429 Too Many Requests	Rate limit exceeded	Too many API calls in time window

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid employee data",
    "details": [
      {
        "field": "hire_date",
        "message": "Date must be in YYYY-MM-DD format"
      }
    ],
    "request_id": "req_123456789"
  }
}
                

SDKs & Tools

Official SDKs

JavaScript/Node.js SDK
Python SDK
PHP SDK
C# .NET SDK
Java SDK

Interactive Tools

Swagger UI for API testing
Postman collection
Code examples repository
API explorer interface

Support Resources

Developer documentation
API status page
Community forums
Technical support

Getting Started

Quick Start Guide

Sign up for a developer account at developer.bizfirstfi.com
Create an application and obtain API credentials
Install the SDK for your preferred programming language
Make your first API call using our interactive documentation
Explore the comprehensive examples in our GitHub repository