API Reference

The Udala REST API lets you build integrations, automate workflows and sync data between Udala and your other systems.

Authentication

Udala uses Bearer token authentication. Generate an API key from Settings → API Keys in your workspace.

All API requests must include the Authorization header and the X-Workspace header identifying which company workspace you're querying:

Authorization: Bearer YOUR_API_KEY
X-Workspace: nexus-group
Content-Type: application/json

Rate Limits

API rate limits by plan:

• Growth: 10,000 requests per day, 100 requests per minute
• Enterprise: Custom limits

Rate limit headers are returned on every response:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1704067200

Error Handling

All errors return a consistent JSON body:

{
  "success": false,
  "statusCode": 422,
  "message": "The email field is required.",
  "timestamp": "2027-01-01T08:00:00.000Z",
  "path": "/api/v1/contacts"
}

Standard HTTP status codes are used:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorised (invalid or missing API key)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found
• 422 - Validation Error
• 429 - Rate Limited
• 500 - Server Error

Invoices

curl -X GET "https://api.udala.africa/api/v1/finance/invoices?status=paid" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace: nexus-group"

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "inv_01hx7k...",
        "number": "INV-2027-0001",
        "customer": { "id": "cust_...", "name": "Dangote Flour Mills" },
        "status": "paid",
        "currency": "NGN",
        "subtotal": 500000,
        "tax": 37500,
        "total": 537500,
        "due_date": "2027-01-31",
        "paid_at": "2027-01-28T14:22:00Z"
      }
    ],
    "pagination": { "page": 1, "per_page": 25, "total": 142, "last_page": 6 }
  },
  "timestamp": "2027-02-01T08:00:00Z"
}

{
  "customer_id": "cust_01hx...",
  "currency": "NGN",
  "due_date": "2027-02-28",
  "payment_terms": "NET_30",
  "line_items": [
    {
      "description": "ERP Implementation - Phase 1",
      "quantity": 1,
      "unit_price": 500000,
      "tax_rate": 7.5
    }
  ],
  "notes": "Payment via bank transfer to GTB account."
}

Employees

curl -X GET "https://api.udala.africa/api/v1/hr/employees" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace: nexus-group"

{
  "first_name": "Adaeze",
  "last_name": "Okafor",
  "email": "ada.okafor@company.com",
  "phone": "+234 801 234 5678",
  "department_id": "dept_...",
  "job_title": "Senior Finance Analyst",
  "employment_type": "FULL_TIME",
  "start_date": "2027-01-15",
  "gross_salary": 450000,
  "salary_currency": "NGN"
}

Contacts (CRM)

{
  "name": "Bayo Adewale",
  "email": "bayo@company.ng",
  "phone": "+234 802 000 1111",
  "company": "Adewale & Co",
  "type": "LEAD",
  "source": "REFERRAL"
}

Webhooks

Udala sends webhook events to your configured endpoint whenever key events happen. Register webhooks from Settings → Webhooks.

POST https://your-server.com/udala-webhook
Content-Type: application/json
X-Udala-Signature: sha256=abc123...

{
  "event": "invoice.paid",
  "workspace": "nexus-group",
  "timestamp": "2027-01-28T14:22:00Z",
  "data": {
    "invoice_id": "inv_01hx7k...",
    "amount": 537500,
    "currency": "NGN",
    "customer_id": "cust_..."
  }
}

Webhook Event Types

• invoice.created - New invoice created
• invoice.paid - Invoice fully paid
• invoice.overdue - Invoice past due date
• employee.created - New employee added
• payroll.approved - Payroll approved by Finance
• deal.won - CRM deal marked as won
• subscription.cancelled - Udala subscription cancelled