API Quickstart - TinyTax
Developers / Quickstart

Quickstart Guide

Submit your first filing in 5 minutes — dormant or trading.

Try the sandbox first: Use a test key (tt_test_...) and magic company numbers to test your integration without making real filings.
1

Get Your API Key

If you don't have a TinyTax account, sign up first. Then:

  1. Go to Profile → API Dashboard
  2. Click Enable API Access
  3. Copy your API key (it starts with tt_live_ or tt_test_)
Important: Your API key is shown only once. Store it securely.

Test keys (tt_test_...) enable sandbox mode - perfect for building and testing your integration. Live keys (tt_live_...) submit real filings.

2

Check Your Filing Allowance

API filings are included with your Portfolio subscription. Each plan includes an annual filing allowance. If you exceed your allowance, overage is billed automatically to your card (plus 20% VAT).

  1. Go to API Dashboard → Billing
  2. Check your current allowance and usage
  3. If you need more filings, upgrade your Portfolio tier
3

Submit a CT600 Filing

Submit a dormant CT600 nil return to HMRC. You only need 4 fields - we derive the rest from Companies House.

Request

curl -X POST https://tinytax.co.uk/api/v1/filings/ct600 \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: ct600-12345678-2024" \
  -H "Content-Type: application/json" \
  -d '{
    "company_number": "12345678",
    "utr": "1234567890",
    "period_end": "2024-12-31",
    "credentials": {
      "government_gateway_id": "123456789012",
      "government_gateway_password": "your_password"
    }
  }'

Response (202 Accepted)

{
  "success": true,
  "data": {
    "filing_id": "fil_abc123def456",
    "status": "submitted",
    "hmrc_correlation_id": "A1B2C3D4E5F6",
    "derived_values": {
      "company_name": "Dormant Example Ltd",
      "period_start": "2024-01-01",
      "declarant_name": "John Smith",
      "declarant_status": "Director"
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
Smart Defaults: We auto-derive company name, period start, and director details from Companies House. You can override any of these by including them in your request.
3b

Submit a Trading CT600

For trading companies, include a financials object with profit & loss, tax adjustments, and balance sheet data. We calculate the tax, generate all documents (CT600, accounts, computations), and submit to HMRC.

Request

curl -X POST https://tinytax.co.uk/api/v1/filings/ct600 \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: ct600-trading-12345678-2025" \
  -H "Content-Type: application/json" \
  -d '{
    "company_number": "12345678",
    "utr": "1234567890",
    "period_end": "2025-03-31",
    "credentials": {
      "government_gateway_id": "123456789012",
      "government_gateway_password": "your_password"
    },
    "financials": {
      "profit_and_loss": {
        "turnover": 120000,
        "cost_of_sales": 45000,
        "staff_costs": 30000,
        "depreciation": 5000,
        "other_operating_expenses": 10000
      },
      "tax_adjustments": {
        "depreciation_addback": 5000,
        "capital_allowances": 3000,
        "disallowable_expenses": 500
      },
      "balance_sheet": {
        "fixed_assets": 25000,
        "current_assets": 40000,
        "creditors_within_one_year": 15000,
        "share_capital": 1000,
        "profit_and_loss_account": 49000
      },
      "prior_year": {
        "fixed_assets": 20000,
        "current_assets": 35000,
        "creditors_within_one_year": 12000,
        "share_capital": 1000,
        "profit_and_loss_account": 42000,
        "turnover": 100000,
        "profit_before_tax": 25000
      },
      "average_employees": 3
    }
  }'

Response (202 Accepted)

{
  "success": true,
  "data": {
    "filing_id": "fil_abc123def456",
    "status": "submitted",
    "filing_type": "trading",
    "submitted_at": "2026-04-06T10:30:00Z",
    "hmrc_correlation_id": "A1B2C3D4E5F6",
    "derived_values": {
      "company_name": "Example Trading Ltd",
      "period_start": "2024-04-01",
      "is_first_year": false,
      "declarant_name": "John Smith",
      "declarant_status": "Director"
    },
    "calculated": {
      "taxable_profit": 32500.00,
      "corporation_tax": 6175.00,
      "marginal_relief": 0.00,
      "effective_rate": 19.00,
      "losses_used": 0.00,
      "losses_carried_forward": 0.00
    }
  }
}
Calculated values: The response includes the computed tax so you can verify the result. The same calculation engine is used for both the API and the web form.

Validate first with dry run

Add "dry_run": true to validate your data and see calculated values without submitting. No idempotency key required, does not count against your filing allowance.

curl -X POST https://tinytax.co.uk/api/v1/filings/ct600 \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_number": "12345678",
    "utr": "1234567890",
    "period_end": "2025-03-31",
    "credentials": {
      "government_gateway_id": "123456789012",
      "government_gateway_password": "your_password"
    },
    "dry_run": true,
    "financials": {
      "profit_and_loss": { "turnover": 120000 },
      "balance_sheet": {
        "fixed_assets": 25000,
        "current_assets": 40000,
        "creditors_within_one_year": 15000,
        "share_capital": 1000,
        "profit_and_loss_account": 49000
      },
      "average_employees": 3
    },
    "first_year": true
  }'
4

Submit Dormant Accounts

Submit dormant accounts to Companies House. Only 3 required fields.

Request

curl -X POST https://tinytax.co.uk/api/v1/filings/accounts \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: accounts-12345678-2024" \
  -H "Content-Type: application/json" \
  -d '{
    "company_number": "12345678",
    "period_end": "2024-12-31",
    "credentials": {
      "company_auth_code": "ABC123"
    }
  }'

Response (202 Accepted)

{
  "success": true,
  "data": {
    "filing_id": "fil_xyz789abc012",
    "status": "submitted",
    "ch_submission_number": "CH-2025-001234",
    "derived_values": {
      "company_name": "Dormant Example Ltd",
      "period_start": "2024-01-01",
      "director_name": "John Smith",
      "share_capital": 100,
      "cash": 100
    }
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440001"
}
5

Check Filing Status

HMRC and Companies House process filings asynchronously. Poll the status endpoint to check progress.

Request

curl https://tinytax.co.uk/api/v1/filings/fil_abc123def456 \
  -H "X-API-Key: $API_KEY"

Response

{
  "success": true,
  "data": {
    "filing_id": "fil_abc123def456",
    "filing_type": "ct600",
    "company_number": "12345678",
    "company_name": "Dormant Example Ltd",
    "period": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    },
    "status": "accepted",
    "hmrc_correlation_id": "A1B2C3D4E5F6",
    "hmrc_iru_number": "1234567890",
    "created_at": "2025-01-15T14:30:00Z",
    "updated_at": "2025-01-15T14:35:00Z"
  }
}

Status Values

Status Description
pending Filing created, not yet submitted
submitted Submitted to HMRC/CH, awaiting response
accepted Successfully accepted by HMRC/CH
rejected Rejected by HMRC/CH
error System error (credentials invalid, timeout, etc.)
Polling Recommendation: Poll every 30 seconds for the first 5 minutes, then every 5 minutes. Most filings complete within 2–5 minutes. If still pending after 30 minutes, contact support.

Handling Rejections and Errors

When a filing is rejected or errors, your balance is automatically released. Poll the status endpoint to see the outcome:

  • rejected — HMRC/CH rejected the filing (e.g. UTR mismatch, period already filed, invalid auth code). Fix the data and resubmit with a new idempotency key.
  • error — transient failure (e.g. gateway timeout). Poll to confirm the status is terminal, then resubmit with a new idempotency key.

Note: The status endpoint currently returns the outcome status (rejected / error) but does not yet include detailed rejection reasons. Detailed error codes and messages will be added in a future update. In the meantime, contact support if you need help diagnosing a rejection.

Always use a new idempotency key when resubmitting. The API caches responses by idempotency key — reusing the same key will replay the original error response, not create a new submission.

Sandbox Error Testing

Use these magic company numbers with a test key to simulate different outcomes:

Company Number Outcome Error
00000001Accepted—
00000002RejectedUTR does not match
00000003RejectedPeriod already filed
00000004ErrorGateway timeout
SC000002RejectedCompany dissolved
NI000002RejectedAuth code invalid

Next Steps

API Reference

Complete endpoint documentation with all request/response schemas.

Authentication

Learn about API keys, rate limits, and idempotency.