Public API

Authentication

Send your API key on every request using either header:

• Authorization: Bearer YOUR_API_KEY
• X-Api-Key: YOUR_API_KEY

Keys use tt_ prefix. Keep them secret — use environment variables, never commit to source control.

Scopes

Each key has scopes that control access. Choose the minimum required:

• read:transactions — List and view transactions
• write:transactions — Create, update, delete transactions
• read:invoices — List and view invoices
• write:invoices — Create, update, delete invoices
• read:tax — View PIT assessments, reliefs, and filing history
• write:tax — File PIT returns
• read:integrations — List connected integrations
• write:integrations — Trigger syncs for integrations
• admin:all — Full access (all endpoints)

Endpoints

All endpoints return JSON. Paginated lists include data and meta (page, limit, total, total_pages).

Health

Transactions

Invoices

Personal Income Tax (PIT)

Remita PIT Payment

Tax Rates

Integrations

Parameters

List endpoints (GET)

• page — Page number (default 1).
• limit — Items per page, 1–50 (default 20).
• status — Filter by status. Transactions: pending, categorized, approved, validated, flagged, rejected, filed. Invoices: draft, pending, submitted, approved, rejected, cancelled.

Create transaction (POST /transactions)

• date (required) — Transaction date (YYYY-MM-DD).
• description (required) — Max 1,000 characters.
• type (required) — One of: income, expense, transfer, journal.
• amount (required) — Positive number, max 999,999,999,999.
• currency — NGN (default), USD, GBP, or EUR.
• category — Max 200 characters.
• counterparty_name — Max 500 characters.
• counterparty_tin — Max 50 characters.
• invoice_number — Max 100 characters.
• notes — Max 2,000 characters.
• line_items — Array of objects (max 100). Each can have: description, quantity, unit_price, amount, tax_code, category.

Create invoice (POST /invoices)

• invoice_number (required) — Max 100 characters.
• issue_date (required) — YYYY-MM-DD.
• total_amount (required) — Non-negative number, max 999,999,999,999.
• currency — NGN (default), USD, GBP, or EUR.
• due_date — YYYY-MM-DD.
• customer_name — Max 500 characters.
• customer_tin — Max 50 characters.
• line_items — Array of objects (max 100).
• notes — Max 2,000 characters.
• branch_id — UUID of the branch.

Request body

• Send JSON with Content-Type: application/json.
• Maximum body size: 256 KB. Larger requests return 413.
• Body must be a JSON object (not an array or primitive).
• PUT requests use field-level allowlisting — only documented fields are accepted. Unknown fields are ignored.

Responses

All responses include these headers:

• X-Request-Id — Unique ID for the request. Include this in support tickets for faster debugging.
• X-API-Version — Current API version (1.0).
• X-RateLimit-Limit — Your rate limit per minute.
• X-RateLimit-Remaining — Requests remaining in current window.

Success (200/201): Body has data (array or object) and for lists meta with page, limit, total, total_pages. Created resources return 201.

Delete (200): Returns { "success": true }.

Rate limiting

Each API key has a per-minute rate limit (default: 1,000 requests/minute, configurable up to 10,000). When exceeded, you'll receive a 429 response with a Retry-After header indicating how many seconds to wait.

Monitor your usage via the X-RateLimit-Limit and X-RateLimit-Remaining headers on every response.

Idempotency

For POST requests (create operations), include an Idempotency-Key header with a unique value (e.g. a UUID). If the same key is sent again within 24 hours, the API returns the original response without creating a duplicate.

curl -X POST "https://api.taxtask.com/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"date": "2026-02-14", "description": "Office supplies", "type": "expense", "amount": 15000}'

This is recommended for all create operations to safely handle retries on network errors.

Errors

Errors return JSON with error (message), code, and request_id:

{
  "error": "Missing required fields: date, description, type, amount",
  "code": "validation_error",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Code examples

Replace YOUR_API_KEY with your key.

Health check (no key)

curl https://api.taxtask.com/v1/health

List transactions

curl "https://api.taxtask.com/v1/transactions?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a transaction

curl -X POST "https://api.taxtask.com/v1/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "date": "2026-02-14",
    "description": "Office rent payment",
    "type": "expense",
    "amount": 250000,
    "currency": "NGN",
    "category": "rent",
    "counterparty_name": "ABC Properties Ltd"
  }'

Update a transaction

curl -X PUT "https://api.taxtask.com/v1/transactions/TRANSACTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "amount": 275000}'

Delete a transaction

curl -X DELETE "https://api.taxtask.com/v1/transactions/TRANSACTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch("https://api.taxtask.com/v1/transactions?page=1&limit=20", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const { data, meta } = await res.json();
console.log(`Page ${meta.page} of ${meta.total_pages}`);

Python

import requests

# List transactions
r = requests.get(
    "https://api.taxtask.com/v1/transactions",
    params={"page": 1, "limit": 20},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = r.json()

# Create a transaction
r = requests.post(
    "https://api.taxtask.com/v1/transactions",
    json={
        "date": "2026-02-14",
        "description": "Client payment received",
        "type": "income",
        "amount": 500000,
    },
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": "unique-request-id-123",
    },
)
print(r.json())

Example success response (list)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "branch_id": "...",
      "type": "expense",
      "source": "api",
      "status": "pending",
      "amount": 250000,
      "currency": "NGN",
      "description": "Office rent payment",
      "transaction_date": "2026-02-14",
      "created_at": "2026-02-14T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "total_pages": 1
  }
}

OpenAPI spec

Download the full OpenAPI 3.0 spec for code generation, Swagger UI, or Postman import: openapi.yaml. Preview it at editor.swagger.io.