Assignar Pay Logo
Sign Up

API Integration

Learn how to integrate with Assignar Pay using our REST API and API keys

API Integration Features

Integrate Assignar Pay with your existing systems and build custom applications using our RESTful API. Access payroll data, manage pay rates, and automate workflows programmatically.

Core API Features

API Keys

Secure authentication for API access. Learn how to:

  • Create and manage API keys with granular permissions
  • Set expiration dates and security scopes
  • Use API keys in your applications
  • Revoke keys when needed

API Documentation

Interactive API documentation with:

  • Complete endpoint reference
  • Request and response schemas
  • Try-it-out functionality
  • Authentication examples

Getting Started

New to the Assignar Pay API? Start with:

  1. API Keys - Create your first API key
  2. API Documentation - Explore available endpoints
  3. Review authentication requirements and best practices

Authentication

The Assignar Pay API uses API key authentication. You can provide your API key in two ways:

  • X-API-KEY header: X-API-KEY: sk_your_api_key_here
  • Authorization Bearer header: Authorization: Bearer sk_your_api_key_here

Both methods are supported, with X-API-KEY taking precedence if both are provided.

API Base URL

All API endpoints are available at:

https://pay.assignar.com/api/v1

Rate Limits

API requests are subject to rate limiting to ensure fair usage and maintain system stability. Rate limits are enforced per API key using a sliding window algorithm.

Default Rate Limits

By default, each API key has the following rate limits:

  • Per minute: 60 requests
  • Per hour: 1,000 requests
  • Per day: 10,000 requests

These limits apply to all API endpoints and are enforced simultaneously. The most restrictive limit determines when rate limiting occurs.

Rate Limit Headers

Every API response includes rate limit information in the following headers:

  • X-RateLimit-Limit: The maximum number of requests allowed in the current window
  • X-RateLimit-Remaining: The number of requests remaining in the current window
  • X-RateLimit-Reset: Unix timestamp indicating when the current window resets
  • Retry-After: Number of seconds to wait before retrying (only present when rate limit is exceeded)

Handling Rate Limits

When you exceed a rate limit, the API returns a 429 Too Many Requests status code with a JSON error response:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 60 requests. Please try again after 45 seconds.",
  "retryAfter": 45
}

Best practices for handling rate limits:

  • Monitor the X-RateLimit-Remaining header to track your usage
  • Implement exponential backoff when you receive a 429 response
  • Use the Retry-After header to determine when to retry
  • Consider implementing request queuing for high-volume applications
  • Cache responses when possible to reduce API calls

Example: Handling Rate Limits

async function makeApiRequest(url, apiKey) {
  const response = await fetch(url, {
    headers: {
      'X-API-KEY': apiKey,
      'Content-Type': 'application/json',
    },
  });

  // Check rate limit headers
  const limit = parseInt(response.headers.get('X-RateLimit-Limit') || '60');
  const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
  const reset = parseInt(response.headers.get('X-RateLimit-Reset') || '0');

  console.log(`Rate limit: ${remaining}/${limit} remaining, resets at ${new Date(reset * 1000)}`);

  if (response.status === 429) {
    const error = await response.json();
    const retryAfter = error.retryAfter || 60;
    
    console.warn(`Rate limit exceeded. Retrying after ${retryAfter} seconds...`);
    
    // Wait and retry
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return makeApiRequest(url, apiKey); // Retry
  }

  return response.json();
}

Requesting Higher Limits

If you need higher rate limits for your use case, please contact support. We can configure custom limits at the account or API key level based on your requirements.

Best Practices

  • Store API keys securely and never commit them to version control
  • Use environment variables for API key storage
  • Rotate API keys regularly for security
  • Set appropriate expiration dates for temporary integrations
  • Use scoped permissions to limit access to only what's needed
  • Monitor API key usage and revoke unused keys
  • Handle rate limits gracefully in your applications

Integration Examples

cURL Example

curl -X GET "https://pay.assignar.com/api/v1/pay-rates" \
  -H "X-API-KEY: sk_your_api_key_here" \
  -H "Content-Type: application/json"

JavaScript/TypeScript Example

const response = await fetch('https://pay.assignar.com/api/v1/pay-rates', {
  headers: {
    'X-API-KEY': process.env.API_KEY,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Python Example

import requests

headers = {
    'X-API-KEY': os.environ['API_KEY'],
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://pay.assignar.com/api/v1/pay-rates',
    headers=headers
)

data = response.json()

What's Next

After setting up API access, you may want to: