API Documentation

Integrate your systems with FINEXA Payroll & Accounting – RESTful APIs for seamless data exchange.

Contents

Overview

The FINEXA API allows developers to programmatically access and manage payroll, accounting, HR, and compliance data. Built with REST principles, it returns JSON responses and uses standard HTTP methods.

Base URL: https://api.finexa.co.za/v1/

Version: v1 (latest)

Data Format: JSON

Authentication

All API requests require an API key. You can obtain your API key from the FINEXA dashboard under Settings → API Keys.

POST /auth/token
Headers:
  Content-Type: application/json
Body:
{
  "api_key": "your_api_key_here"
}
Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Include the access token in subsequent requests:

Authorization: Bearer <access_token>

Base URL

All endpoints are relative to:

https://api.finexa.co.za/v1/

Example full URL: https://api.finexa.co.za/v1/companies

Rate Limiting

API requests are limited to 100 requests per minute per API key. If exceeded, you will receive a 429 Too Many Requests response.

Response headers include:

  • X-RateLimit-Limit – requests allowed per minute
  • X-RateLimit-Remaining – remaining requests in current window
  • X-RateLimit-Reset – time until limit resets (UTC epoch seconds)

Error Handling

FINEXA API uses standard HTTP status codes:

CodeMeaning
200Success
201Created
400Bad Request – missing or invalid parameters
401Unauthorized – invalid or missing API key/token
403Forbidden – insufficient permissions
404Not Found
429Too Many Requests – rate limit exceeded
500Internal Server Error

Error responses include a JSON body with details:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'email' field must be a valid email address."
  }
}

API Endpoints

Companies

GET /companies – List all companies
GET /companies/{id} – Get a specific company
POST /companies – Create a new company
PUT /companies/{id} – Update a company
DELETE /companies/{id} – Delete a company

Example Request (Create Company):

POST /v1/companies
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Acme (Pty) Ltd",
  "tax_id": "1234567890",
  "vat_number": "ZA1234567890",
  "email": "finance@acme.co.za",
  "phone": "011 123 4567",
  "address": "123 Main Street, Sandton"
}

Employees

GET /companies/{company_id}/employees – List employees
POST /companies/{company_id}/employees – Add employee
PUT /employees/{id} – Update employee

Invoices (Accounting)

GET /companies/{company_id}/invoices – List invoices
POST /companies/{company_id}/invoices – Create invoice
POST /invoices/{id}/pay – Record payment

Payroll

GET /companies/{company_id}/payroll/runs – List payroll runs
POST /companies/{company_id}/payroll/process – Run payroll
GET /employees/{id}/payslips – Get payslips for employee

Banking

GET /companies/{company_id}/bank-accounts – List bank accounts
POST /companies/{company_id}/transactions – Add transaction

Webhooks

FINEXA can send real‑time notifications to your server when events occur (e.g., invoice paid, payroll completed).

Register a webhook URL via the dashboard. We will send a POST request with a JSON payload.

Example payload (invoice.paid):

{
  "event": "invoice.paid",
  "timestamp": "2025-04-20T10:30:00Z",
  "data": {
    "invoice_id": 12345,
    "customer_name": "ABC Corp",
    "amount": 15000.00
  }
}

To verify authenticity, FINEXA includes a signature header: X-FINEXA-Signature. Validate using your webhook secret.

SDKs & Libraries

Official SDKs are available for popular languages:

  • PHP: composer require finexa/api-php
  • Python: pip install finexa-api
  • Node.js: npm install finexa-sdk
  • Java: Maven central – com.finexa:api-client

Example using PHP SDK:

$finexa = new Finexa\Client('your_api_key');
$company = $finexa->companies()->create([
  'name' => 'Acme (Pty) Ltd',
  'tax_id' => '1234567890'
]);

Support

Need help integrating? Contact our developer support team: