Documentation
Start typing to search…
  1. Audit1 - API

Quick Reference

Quick reference for Audit1 Developer API - cheat sheet for common tasks

API Quick Reference

One-page reference for the most common API operations.

🔑 Authentication

Authorization: Bearer audit1_test_sk_1234567890abcdef1234567890abcdef
Key PrefixEnvironmentData Type
audit1_test_sk_*SandboxTest data
audit1_live_sk_*ProductionReal data

🌐 Base URL

https://api.audit1.info/api/v1

Same URL for both environments - environment detected from API key prefix.

📡 Endpoints

Submit Payroll Report

POST /payroll/reports

Request:

{
  "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
  }
}

Response (202):

{
  "report_id": "PR_1234567890",
  "status": "processing",
  "environment": "sandbox",
  "estimated_processing_time": "1-2 minutes"
}

Sync Employee Changes

POST /employees/sync

Hire Employee:

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

Terminate Employee:

{
  "employer_id": "EMP_12345",
  "employees": [
    {
      "employee_id": "EE_001",
      "action": "terminate",
      "termination_date": "2024-06-30",
      "termination_reason": "Resigned"
    }
  ]
}

Update Employee:

{
  "employer_id": "EMP_12345",
  "employees": [
    {
      "employee_id": "EE_001",
      "action": "update",
      "classification_code": "5403",
      "hourly_rate": 35.00
    }
  ]
}

Check File Status

GET /files/status/:file_id

Response (200):

{
  "file_id": "FILE_123",
  "status": "completed",
  "environment": "sandbox",
  "records_processed": 50,
  "processing_time": "5 minutes"
}

📋 Common Headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

🚦 Response Codes

CodeStatusMeaning
200OKRequest successful
202AcceptedProcessing asynchronously
400Bad RequestInvalid request data
401UnauthorizedInvalid/missing API key
404Not FoundResource doesn't exist
429Too Many RequestsRate limit exceeded
500Server ErrorInternal error

❌ Common Errors

Invalid API Key

{
  "error": "Authentication Failed",
  "message": "Invalid API key format"
}

Fix: Ensure key starts with audit1_test_sk_ or audit1_live_sk_

Missing Required Fields

{
  "error": "Validation Error",
  "message": "Missing required fields: employees"
}

Fix: Include all required fields in request body

Rate Limit

{
  "error": "Rate Limit Exceeded",
  "message": "Too many requests. Retry after 60 seconds.",
  "details": {
    "retry_after": 60
  }
}

Fix: Implement exponential backoff retry

🔄 Retry Logic

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      const status = error.response?.status;
      
      // Don't retry client errors (except rate limits)
      if (status >= 400 && status < 500 && status !== 429) {
        throw error;
      }
      
      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

📦 Required Fields

Payroll Report

FieldTypeRequiredFormat
employer_idstring✅ Yes-
period_startstring✅ YesYYYY-MM-DD
period_endstring✅ YesYYYY-MM-DD
employeesarray✅ YesMin 1 employee
payroll_dataobject✅ YesTotals object

Employee Object

FieldTypeRequiredFormat
employee_idstring✅ Yes-
namestring✅ Yes-
classification_codestring✅ YesNCCI code
hours_workednumber✅ Yes-
gross_wagesnumber✅ Yes-
overtime_hoursnumber❌ No-
overtime_paynumber❌ No-

Employee Sync (Hire)

FieldTypeRequired
employee_idstring✅ Yes
actionstring✅ Yes (hire)
namestring✅ Yes
hire_datestring✅ Yes
classification_codestring✅ Yes
hourly_ratenumber❌ No

Employee Sync (Terminate)

FieldTypeRequired
employee_idstring✅ Yes
actionstring✅ Yes (terminate)
termination_datestring✅ Yes
termination_reasonstring❌ No

🧪 Testing

Test API Key

# Get test key from Dashboard
export AUDIT1_API_KEY="audit1_test_sk_..."

# Test request
curl -X POST https://api.audit1.info/api/v1/payroll/reports \
  -H "Authorization: Bearer $AUDIT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d @test-payload.json

Test Payload

Save as test-payload.json:

{
  "employer_id": "EMP_TEST_001",
  "period_start": "2024-01-01",
  "period_end": "2024-03-31",
  "employees": [
    {
      "employee_id": "EE_TEST_001",
      "name": "Test Employee",
      "classification_code": "8810",
      "hours_worked": 520,
      "gross_wages": 26000
    }
  ],
  "payroll_data": {
    "total_payroll": 26000,
    "total_hours": 520,
    "officer_payroll": 0,
    "subcontractor_payments": 0
  }
}

🔐 Security Checklist

  • Store API keys in environment variables
  • Never commit keys to version control
  • Use test keys for development
  • Rotate keys every 90 days
  • Monitor for unusual activity
  • Use HTTPS for all requests
  • Validate webhook signatures
  • Implement rate limiting
  • Log all API errors

📚 Quick Links

💡 Pro Tips

  1. Environment Detection: Same URL, different keys = different environments
  2. Idempotency: Use unique IDs to prevent duplicate submissions
  3. Error Handling: Always implement retry logic with exponential backoff
  4. Testing: Test in sandbox first, then move to production
  5. Monitoring: Track API usage and error rates
  6. Webhooks: Use webhooks for real-time updates instead of polling
  7. Batch Processing: Submit multiple reports with delay between batches
  8. Rate Limits: Stay under 100 requests/minute to avoid throttling

🆘 Need Help?

Updated about 17 hours ago