# Base URL
https://api.audit1.info/api/v1


# Authentication
Authorization: Bearer audit1_test_sk_YOUR_KEY_HERE

# Content Type
Content-Type: application/json

# Submit payroll report
curl -X POST https://api.audit1.info/api/v1/payroll/reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employer_id": "EMP_12345",
    "period_start": "2024-01-01",
    "period_end": "2024-03-31",
    "employees": [...],
    "payroll_data": {...}
  }'

Authorization: Bearer audit1_test_sk_1234567890abcdef1234567890abcdef

curl -X POST https://api.audit1.info/api/v1/payroll/reports \
  -H "Authorization: Bearer audit1_test_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"employer_id": "EMP_001", ...}'

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://api.audit1.info/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.AUDIT1_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Make request
const response = await client.post('/payroll/reports', payloadData);

import requests
import os

headers = {
    'Authorization': f'Bearer {os.getenv("AUDIT1_API_KEY")}',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.audit1.info/api/v1/payroll/reports',
    headers=headers,
    json=payload_data
)

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.BaseAddress = new Uri("https://api.audit1.info/api/v1");
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AUDIT1_API_KEY"));

var response = await client.PostAsJsonAsync("/payroll/reports", payloadData);

Authorization: Bearer YOUR_API_KEY

curl -X POST https://api.audit1.info/api/v1/payroll/reports \
  -H "Authorization: Bearer audit1_live_sk_abc123..." \
  -H "Content-Type: application/json" \
  -d '{...}'

POST /api/v1/payroll/reports

{
  "employer_id": "EMP_12345",
  "period_start": "2024-01-01",
  "period_end": "2024-03-31",
  "employees": [
    {
      "employee_id": "EE_001",
      "name": "John Smith",
      "classification_code": "8810",
      "hours_worked": 520,
      "gross_wages": 26000
    }
  ],
  "payroll_data": {
    "total_payroll": 26000,
    "total_hours": 520,
    "officer_payroll": 0,
    "subcontractor_payments": 0
  }
}

POST /api/v1/employees/sync

{
  "employer_id": "EMP_12345",
  "employees": [
    {
      "employee_id": "EE_NEW_001",
      "action": "hire",
      "name": "Jane Doe",
      "hire_date": "2024-02-01",
      "classification_code": "8810",
      "hourly_rate": 30.00
    }
  ]
}

GET /api/v1/files/status/:id

{
  "file_id": "FILE_123",
  "status": "completed",
  "records_total": 150,
  "records_processed": 150,
  "records_failed": 0
}

{
  "owner_id": "your-entity-id",
  "owner_type": "employer|payroll_company|software_company", 
  "environment": "sandbox|production"
}

{
  "apiKey": {
    "_id": "507f1f77bcf86cd799439011",
    "id": "ak_12345",
    "key": "ak_prod_1234567890abcdef...",
    "environment": "production",
    "owner_id": "your-entity-id",
    "owner_type": "employer",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
  },
  "secret": "sk_prod_abcdef1234567890..."
}
  ## Platform Architecture Snapshot

  The Developer API mirrors how the Audit1 workers' compensation stack is assembled:

  1. **Experience Layer** – employer and carrier portals powered by Audit1 UI components.
  2. **Service Layer** – stateless Node services (Developer API, Notification Handler, Ledger) deployed to Cloud Run.
  3. **Data Layer** – MongoDB Atlas clusters split by environment with regional failover.
  4. **Integration Fabric** – webhook dispatcher, SFTP collectors, and third-party connectors (Paylocity, UKG, Hartford, etc.).

{
  "apiKeys": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "id": "ak_12345",
      "key": "ak_prod_1234567890abcdef...",
      "environment": "production",
      "owner_id": "your-entity-id",
      "owner_type": "employer",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

{
  "message": "api_key_deleted"
}

{
  "owner_id": "your-entity-id",
  "owner_type": "employer|payroll_company|software_company",
  "url": "https://your-domain.com/webhooks/audit1",
  "events": ["policy.created", "payment.processed", "employee.updated"]
}

{
  "webhook": {
    "_id": "507f1f77bcf86cd799439012",
    "id": "wh_12345",
    "url": "https://your-domain.com/webhooks/audit1", 
    "events": ["policy.created", "payment.processed"],
    "owner_id": "your-entity-id",
    "owner_type": "employer",
    "is_active": true,
    "created_at": "2024-01-15T10:35:00.000Z",
    "updated_at": "2024-01-15T10:35:00.000Z"
  },
  "secret": "whsec_1234567890abcdef..."
}

Audit1-Signature: t=1642291200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/audit1', (req, res) => {
  const signature = req.headers['audit1-signature'];
  const payload = req.body;
  
  // Verify signature
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  // Handle the event
  switch (event.type) {
    case 'policy.created':
      handlePolicyCreated(event.data);
      break;
    case 'payment.processed':
      handlePaymentProcessed(event.data);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
  
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const elements = signature.split(',');
  const timestamp = elements[0].split('=')[1];
  const v1 = elements[1].split('=')[1];
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + payload)
    .digest('hex');
    
  return crypto.timingSafeEqual(
    Buffer.from(v1, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

{
  "id": "evt_1234567890",
  "type": "policy.created", 
  "created_at": "2024-01-15T10:40:00.000Z",
  "data": {
    "policy": {
      "id": "pol_12345",
      "employer_id": "emp_67890",
      "policy_number": "POL-2024-001",
      "effective_date": "2024-02-01",
      "premium": 1500.00,
      "status": "active"
    }
  },
  "metadata": {
    "source": "audit1_system",
    "environment": "production"
  }
}

# Sandbox request (test data)
curl -H "Authorization: Bearer audit1_test_sk_abc123..." \
  https://api.audit1.info/api/v1/payroll/reports

# Production request (real data)
curl -H "Authorization: Bearer audit1_live_sk_xyz789..." \
  https://api.audit1.info/api/v1/payroll/reports

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

# Use the generated URL for webhooks
# https://abc123.ngrok.io/webhooks/audit1

{
  "error": "Error type",
  "message": "Human-readable description",
  "details": {
    "field": "Additional context"
  }
}

{
  "error": "Validation Error",
  "message": "Missing required fields: employees",
  "details": {
    "required": ["employer_id", "period_start", "period_end", "employees", "payroll_data"]
  }
}

{
  "error": "Authentication Failed",
  "message": "Invalid API key format. Expected audit1_test_sk_* or audit1_live_sk_*"
}

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Please retry after 60 seconds.",
  "details": {
    "retry_after": 60,
    "limit": 100,
    "window": "1 minute"
  }
}

async function retryRequest(fn, maxRetries = 3) {
  let lastError;
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      
      // Don't retry client errors (4xx except 429)
      if (error.status >= 400 && error.status < 500 && error.status !== 429) {
        throw error;
      }
      
      // Calculate backoff: 1s, 2s, 4s, 8s...
      const backoffMs = Math.min(Math.pow(2, i) * 1000, 30000);
      
      console.log(`Retry ${i + 1}/${maxRetries} after ${backoffMs}ms`);
      await new Promise(resolve => setTimeout(resolve, backoffMs));
    }
  }
  
  throw lastError;
}

// Usage
const result = await retryRequest(() => 
  submitPayrollReport(data)
);

{
  "error": "Validation Error",
  "message": "Invalid employee data",
  "details": {
    "employees[0].classification_code": "Required field missing",
    "employees[1].gross_wages": "Must be a positive number"
  }
}

{
  "error": "Validation Error",
  "message": "Invalid date format for period_start",
  "details": {
    "expected": "YYYY-MM-DD",
    "received": "01/15/2024"
  }
}

function logApiError(error, context) {
  console.error({
    timestamp: new Date().toISOString(),
    error_type: error.name,
    status_code: error.status,
    message: error.message,
    endpoint: context.endpoint,
    method: context.method,
    request_id: error.response?.headers?.['x-request-id'],
    environment: process.env.NODE_ENV,
    stack: error.stack
  });
}

{
  "error": "owner_id_required",
  "message": "The owner_id field is required",
  "code": "VALIDATION_ERROR",
  "timestamp": "2024-01-15T10:45:00.000Z"
}

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 499  
X-RateLimit-Reset: 1642291260

const response = await fetch('/api/v1/api-keys', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (response.status === 429) {
  const resetTime = response.headers.get('X-RateLimit-Reset');
  const waitTime = (resetTime * 1000) - Date.now();
  
  console.log(`Rate limited. Waiting ${waitTime}ms`);
  await new Promise(resolve => setTimeout(resolve, waitTime));
  
  // Retry request
}