Get Your API Credentials

Generate an API key from your portal settings.

Navigate to Settings → API Keys in your portal. Click "Generate New Key" to create a credential pair.

API Key ID — used in the request header
API Secret — shown once at creation, store it securely

Keep it safe. The API secret is only shown once. If you lose it, revoke the key and generate a new one.

You can create multiple keys for different environments (staging, production) and revoke any key at any time.

Authenticate Your Request

All API calls require a Bearer token in the Authorization header.

Include your API key in the Authorization header of every request:

POST /api/v1/files
Authorization: Bearer your_api_key_here
Content-Type: application/json

Base URL. All API endpoints use https://api.audit1.com as the base URL. See the full authentication docs for details.

Submit Payroll Data

Send a POST request with your payroll rows.

Submit payroll data as a JSON array of employee rows. Each row needs at minimum:

first_name and last_name
state — two-letter abbreviation (e.g., "CA", "FL")
class_code — NCCI class code (e.g., "8810")
gross_wages — gross pay for the period (in dollars)
check_date — pay date in YYYY-MM-DD format

{
  "policy_number": "WC-2026-001",
  "employer_fein": "12-3456789",
  "rows": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "state": "FL",
      "class_code": "8810",
      "gross_wages": 3250.00,
      "check_date": "2026-03-15"
    }
  ]
}

The platform validates each row against your policy's class codes, states, and locations. Invalid rows are flagged but don't block valid ones.

Handle the Response

The API returns a file ID for tracking and a summary of validation results.

A successful submission returns a 202 Accepted response with a file ID:

{
  "status": "accepted",
  "file_id": "663a1b2c3d4e5f6789012345",
  "rows_received": 1,
  "message": "File created and queued for processing"
}

Processing happens asynchronously through three phases:

Phase 1: Validation — class codes, states, and WC rules checked
Phase 2: Wage Calculation — auditable wages computed with caps and exclusions
Phase 3: Premium Calculation — net rates applied to produce premium amounts

Error responses. A 409 Conflict means the policy is expired. A 422 Unprocessable means required fields are missing. Check the errors array for details.

Check Processing Status

Poll the file endpoint to see validation and premium results.

Use the file ID from step 3 to check processing status:

GET /api/v1/files/{file_id}/status
Authorization: Bearer your_api_key_here

The response includes the current phase, row-level results, and premium totals once Phase 3 completes.

You're set! For production use, consider setting up webhooks to receive real-time notifications instead of polling. Check the full API reference for all available endpoints.

Continue learning

Next tutorial Setting Up Webhooks Receive real-time notifications for file processing events. Related SFTP Integration Guide Set up automated file delivery via SFTP.