Partner API

Endpoint

POST /api/v1/activate

Use your partner API key in the X-API-Key header. Request body requires company_number and email. external_id is optional.

Example Request

curl -X POST https://tinytax.co.uk/api/v1/activate \
  -H "X-API-Key: tt_live_your_partner_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "company_number": "12345678",
    "email": "owner@example.com",
    "external_id": "cb-customer-789"
  }'

Example Response (201 Created)

{
  "success": true,
  "data": {
    "activation_url": "https://clearbookstax.co.uk/activate/eyJpdiI6Ii4uLiIsInRhZyI6Ii4uLiIsImRhdGEiOiIuLi4ifQ",
    "company_number": "12345678",
    "email": "owner@example.com",
    "external_id": "cb-customer-789"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Trial Balance Import

POST /api/v1/trial-balance

Push structured trial balance data so the submission form is pre-populated when the customer arrives. Requires an Idempotency-Key header and an active entitlement (call POST /activate first).

Example Request

curl -X POST https://tinytax.co.uk/api/v1/trial-balance \
  -H "X-API-Key: tt_live_your_partner_key_here" \
  -H "Idempotency-Key: tb-import-12345678-2026-03-31" \
  -H "Content-Type: application/json" \
  -d '{
    "company_number": "12345678",
    "period_end": "2026-03-31",
    "period_start": "2025-04-01",
    "company_type": "trading",
    "accounts": [
      { "code": "1001001", "name": "Revenue - Sales", "debit": 0, "credit": 85000.00 },
      { "code": "4001001", "name": "Salary/PAYE/NI", "debit": 35000.00, "credit": 0 },
      { "code": "4008002", "name": "Client Entertaining", "debit": 1500.00, "credit": 0 }
    ]
  }'

Example Response (201 Created)

{
  "success": true,
  "data": {
    "import_id": "tbi_a1b2c3d4e5f6g7h8",
    "company_number": "12345678",
    "period_end": "2026-03-31",
    "accounts_count": 3,
    "mapped_count": 3,
    "unmapped_count": 0,
    "mapped_totals": {
      "pl_turnover": 85000,
      "pl_staff_costs": 35000,
      "pl_other_charges": 1500
    },
    "disallowable_expenses": {
      "total": 1500.00,
      "accounts": [
        { "code": "4008002", "name": "Client Entertaining", "amount": 1500.00 }
      ]
    },
    "created_at": "2026-02-12T14:30:00Z"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Integration Pattern

1. User clicks "Start tax filing" inside your platform.
2. Your backend calls POST /api/v1/activate.
3. Your backend calls POST /api/v1/trial-balance with the accounts data.
4. Your backend redirects user to the returned activation_url.
5. The user lands on TinyTax with their accounts already mapped.

Security Notes

• Tokens are encrypted (AES-256-GCM) and opaque to clients.
• Tokens are single-use and short-lived.
• Access is controlled by partner API key and partner-domain routing.