REST API reference

1. Base URL & environments

All endpoints require HTTPS. HTTP requests are rejected at the load balancer with no redirect. TLS 1.3 is the minimum supported version; TLS 1.2 is supported for legacy bank-feed callbacks only.

2. Authentication

HIBR supports two authentication models. Pick based on who is making the call:

API keys — for server-to-server integrations

Generate a key in Settings → Developers → API Keys. Pass it as a Bearer token:

Authorization: Bearer hibr_live_xxxxxxxxxxxxxxxxxxxx

Key types:

• hibr_live_* — production environment
• hibr_test_* — sandbox environment

Keys are scoped at creation. Available scopes:

• read:invoices, write:invoices
• read:customers, write:customers
• read:payments, write:payments
• read:vat, write:vat
• read:payroll, write:payroll
• read:reports
• * — full access (use with care)

Keys are revocable per-key without affecting other keys. Revoked keys take effect within 60 seconds.

OAuth 2.0 — for third-party applications

Authorization Code flow with PKCE. Use this when you're building an application that HIBR customers will install. Endpoints:

Register your application in Settings → Developers → OAuth Apps to get a client ID and client secret. Apply for partner status to publish your app to the HIBR App Directory.

3. Versioning

API version is pinned per-request via the Hibr-Version header. The version is a date string. The launch version is 2026-10-01.

Hibr-Version: 2026-10-01

If no version is specified, requests use the account's default version (set at account creation; can be changed in Settings → Developers → API Version).

Versioning rules:

• Patch-level changes (typo in error message, new optional response field, new error code) — no version change required.
• Minor changes (new endpoint, new optional request parameter, new resource) — no version change required.
• Breaking changes (removed field, changed field type, renamed parameter, changed default behavior) — new version. Old versions remain supported for at least 18 months from new version release.

Deprecation notices are sent via the hibr.api.deprecation webhook event and via email to all developer account contacts at least 12 months before sunset.

4. Request format

All POST, PATCH, and DELETE requests use JSON. Set Content-Type: application/json.

# Standard request shape
POST /v1/invoices HTTP/1.1
Host: api.hibr.ai
Authorization: Bearer hibr_live_xxx
Content-Type: application/json
Idempotency-Key: 9f8e7d6c-5b4a-3210-fedc-ba9876543210
Hibr-Version: 2026-10-01

{
  "customer_id": "cust_01HFQA...",
  "lines": [ ... ]
}

GET requests do not have a request body. Filter and sort using query parameters (see §11).

5. Response format & envelope

Successful responses return the resource directly (no wrapping envelope). HTTP 2xx for success, 4xx for client error, 5xx for server error.

# Single resource — 200 OK
{
  "id": "inv_01HFQB...",
  "object": "invoice",
  "invoice_no": "INV-2026-001234",
  ...
}

# List response — 200 OK
{
  "object": "list",
  "data": [ ... ],
  "pagination": {
    "next_cursor": "eyJ0IjoxNzAw...",
    "has_more": true
  }
}

Every resource includes an object field naming the type. This makes generic deserialization easy in typed languages.

6. Money & currency

Amounts are integers in minor currency units. For AED, that means fils (1 AED = 100 fils). So 525000 means AED 5,250.00.

Multi-currency: every monetary field has a paired _currency field. Internal storage is always AED-equivalent at the transaction-date FX rate; the original currency is preserved alongside.

7. Dates & timezones

• Dates (e.g., invoice_date): ISO 8601 date format. "2026-10-15".
• Datetimes (e.g., created_at): RFC 3339 with explicit timezone, always UTC. "2026-10-15T09:32:14Z".
• VAT period dates: ISO 8601 date format, representing the inclusive period start and end.

The customer's local timezone is stored at the account level (Asia/Dubai by default for UAE customers). The API converts datetimes to UTC on input and returns UTC on output; client-side display formatting is your responsibility.

8. Resource IDs

All resource IDs are prefixed with a 3–5 character type identifier, followed by an underscore, followed by a 26-character ULID. Example: inv_01HFQB9XTRP3K2Q5HW7Z3V8YJN.

ID prefixes:

9. Idempotency

Every state-changing request supports an optional Idempotency-Key header. Send a unique key per logical operation. HIBR stores the response under that key for 24 hours. Replaying the same request with the same key returns the cached response — no duplicate invoice, no duplicate payment.

Idempotency-Key: 9f8e7d6c-5b4a-3210-fedc-ba9876543210

Use a UUID v4 per logical operation, not per HTTP retry. The library SDKs handle this automatically.

10. Pagination

List endpoints use cursor-based pagination. Pass ?limit=N&cursor=XYZ. Default limit is 50; maximum is 200.

GET /v1/invoices?limit=50&cursor=eyJ0IjoxNzAw...

The next cursor is in the response: pagination.next_cursor. When has_more is false, you've reached the end.

11. Filtering & sorting

List endpoints accept filter and sort parameters:

GET /v1/invoices?status=paid&invoice_date.gte=2026-01-01&sort=invoice_date:desc

Filter operators (suffixed with a dot):

• .eq — equal (default if no operator)
• .gte, .lte, .gt, .lt — comparisons
• .in — one of (comma-separated values)
• .contains — substring match (string fields only)

12. Errors

Error responses use a stable structure:

# 400 Bad Request
{
  "error": {
    "code": "invalid_request_error",
    "message": "The 'amount' field must be a positive integer in fils.",
    "field": "lines[0].unit_price",
    "docs_url": "https://hibr.ai/developers/api/#money",
    "request_id": "req_01HFQB..."
  }
}

13. Rate limits

Per-tier limits, applied per API key:

Rate-limit headers on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1729000080

When you hit a 429, the Retry-After header tells you how many seconds to wait. The SDK clients implement automatic exponential backoff respecting this header.

14. Resource catalog (launch)

The 16 resources available at launch. Each supports the standard verbs unless noted.

Accounting core

Tax

Payroll

Webhooks

Each resource follows a predictable verb pattern:

15. API changelog policy

Every API change is documented at https://api.hibr.ai/changelog with the date, version, type of change (additive / behavior / breaking), and which endpoints are affected.

• Additive changes (new endpoint, new optional field) are announced in advance via the developer newsletter.
• Behavior changes within a version (bug fixes, performance improvements) are noted in the changelog.
• Breaking changes get a new dated version. The old version is supported for at least 18 months.