Quickstart Guide

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_)

API filings cost £20 each, charged only when HMRC/CH accepts the filing.

1. Go to API Dashboard → Billing
2. Click Top Up Balance
3. Choose an amount and complete payment via Stripe

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"
}

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"
}

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