API docs by Redocly

Savin Hood API (1.0.0)

Download OpenAPI specification:Download

URL: https://savinhood.com

UK tax calculation and optimisation API. Calculate income tax, National Insurance, child benefit charges, and discover tax-saving strategies for PAYE employees and limited company contractors.

api

api_auth_csrf_retrieve

Get CSRF token for cross-origin requests.

This endpoint allows frontend applications to obtain a CSRF token before making state-changing requests (POST, PUT, DELETE).

Returns: 200: CSRF token in response body and as cookie

Example response: {"csrfToken": "abc123..."}

Authorizations:
cookieAuthbasicAuthNone

Responses

api_auth_login_create

Send magic link to user's email for passwordless login.

POST /api/auth/magic-link/login Body: {"email": "user@example.com"} Returns: 204 No Content (doesn't reveal if email exists)

Creates magic link token without creating user (user created on verification). Sends email with magic link that expires in 15 minutes.

Authorizations:
cookieAuthbasicAuthNone
Request Body schema:
required
email
required
string <email>

Email address to send magic link to

Responses

Request samples

Content type
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "email": "user@example.com"
}

api_auth_logout_create

Log out the current user.

POST /api/auth/logout Returns: 204 No Content

Destroys the Django session.

Authorizations:
cookieAuthbasicAuth

Responses

api_auth_session_retrieve

Get current session information.

GET /api/auth/session Returns: 200 OK always with user data if authenticated, null if not

Response:

  • Authenticated: {"user": {...}, "subscription": {...}, "requires_payment": bool}
  • Not authenticated: {"user": null, "subscription": null, "requires_payment": false}
Authorizations:
cookieAuthbasicAuthNone

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "external_id": "95c35493-41aa-44f8-9154-5a25cbbc1865",
  • "email": "user@example.com",
  • "tax_code": "string",
  • "created_at": "2019-08-24T14:15:22Z"
}

api_auth_verify_create

Verify magic link token and log user in.

POST /api/auth/magic-link/verify Body: {"token": "abc123..."} Returns: 204 No Content with session cookie

Validates token is not expired and not already used. Marks token as used after successful verification. Creates Django session for the user.

CSRF exempt because the magic link token itself is the security mechanism.

Authorizations:
cookieAuthbasicAuthNone
Request Body schema:
required
token
required
string <= 64 characters

Magic link token from email

Responses

Request samples

Content type
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

api_calculator_create

Calculate comprehensive tax report for household.

Accepts household data and returns full calculator report including:

  • Tax calculations and breakdowns
  • HMRC pension topups
  • Gift Aid charity topups
  • Tax optimisation strategies
  • Child benefit charges
  • Remaining SIPP allowance
  • Marginal tax rates
Authorizations:
cookieAuthbasicAuthNone
Request Body schema:
primary_tax_code
string <= 20 characters
Default: "1257L"
primary_gross_salary
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
primary_salary_sacrifice_contributions
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
primary_pension_contribution
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
primary_pension_contribution_unit
string
Default: "amount"
Enum: "amount" "percentage"
  • amount - amount
  • percentage - percentage
primary_pension_contribution_type
string
Default: "relief_at_source"
Enum: "relief_at_source" "salary_sacrifice" "net_pay"
  • relief_at_source - relief_at_source
  • salary_sacrifice - salary_sacrifice
  • net_pay - net_pay
primary_employer_pension_contribution
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
primary_employer_pension_contribution_unit
string
Default: "amount"
Enum: "amount" "percentage"
  • amount - amount
  • percentage - percentage
primary_payroll_giving_donations
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
primary_gift_aid_donations
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
primary_taxable_benefits
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
partner_tax_code
string or null <= 20 characters
partner_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_salary_sacrifice_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_net_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
(PartnerNetPensionContributionsTypeA40Enum (string or null)) or (NullEnum (any or null))
partner_employer_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
(PartnerEmployerPensionContributionsTypeA40Enum (string or null)) or (NullEnum (any or null))
partner_payroll_giving_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_gift_aid_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_taxable_benefits
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Array of objects (ChildInput)
claims_child_benefit
boolean
Default: false

Responses

Request samples

Content type
{
  • "primary_tax_code": "1257L",
  • "primary_gross_salary": "0.00",
  • "primary_salary_sacrifice_contributions": "0.00",
  • "primary_pension_contribution": "0.00",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "0.00",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_payroll_giving_donations": "0.00",
  • "primary_gift_aid_donations": "0.00",
  • "primary_taxable_benefits": "0.00",
  • "partner_tax_code": "string",
  • "partner_gross_salary": "string",
  • "partner_salary_sacrifice_contributions": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_payroll_giving_donations": "string",
  • "partner_gift_aid_donations": "string",
  • "partner_taxable_benefits": "string",
  • "children": [
    ],
  • "claims_child_benefit": false
}

Response samples

Content type
application/json
{
  • "primary_tax_code": "1257L",
  • "primary_gross_salary": "0.00",
  • "primary_salary_sacrifice_contributions": "0.00",
  • "primary_pension_contribution": "0.00",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "0.00",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_payroll_giving_donations": "0.00",
  • "primary_gift_aid_donations": "0.00",
  • "primary_taxable_benefits": "0.00",
  • "partner_tax_code": "string",
  • "partner_gross_salary": "string",
  • "partner_salary_sacrifice_contributions": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_payroll_giving_donations": "string",
  • "partner_gift_aid_donations": "string",
  • "partner_taxable_benefits": "string",
  • "children": [
    ],
  • "claims_child_benefit": false
}

api_calculator_contractor_create

Calculate contractor results from input payload.

Authorizations:
cookieAuthbasicAuthNone
Request Body schema:
required
annual_revenue
required
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

Annual company revenue

business_expenses
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"

Annual deductible business expenses

retained_profits
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
Default: "0.00"

Retained profits from prior years

total_pension_contribution
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"

Employer pension contribution

eligible_for_employment_allowance
boolean
Default: false
associated_companies
integer >= 0
Default: 0
vat_registered
boolean
Default: false
vat_using_flat_rate_scheme
boolean
Default: false
vat_flat_rate_percentage
string or null <decimal> ^-?\d{0,2}(?:\.\d{0,2})?$
quarterly_goods_cost
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
director_salary
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Director salary (e.g. £12,570)

director_shareholding_percentage
string <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$
Default: "100.00"
director_self_employment_income
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
director_other_income
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
director_tax_code
string <= 20 characters
Default: "1257L"
director_personal_pension
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
director_charitable_donations
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
partner_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_shareholding_percentage
string or null <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$
partner_self_employment_income
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_other_income
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_tax_code
string or null <= 20 characters
partner_personal_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_charitable_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Array of objects (ChildInput)
claims_child_benefit
boolean
Default: false
total_dividends
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
retain_this_year
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

Responses

Request samples

Content type
{
  • "annual_revenue": "string",
  • "business_expenses": "0.00",
  • "retained_profits": "0.00",
  • "total_pension_contribution": "0.00",
  • "eligible_for_employment_allowance": false,
  • "associated_companies": 0,
  • "vat_registered": false,
  • "vat_using_flat_rate_scheme": false,
  • "vat_flat_rate_percentage": "string",
  • "quarterly_goods_cost": "string",
  • "director_salary": "string",
  • "director_shareholding_percentage": "100.00",
  • "director_self_employment_income": "0.00",
  • "director_other_income": "0.00",
  • "director_tax_code": "1257L",
  • "director_personal_pension": "0.00",
  • "director_charitable_donations": "0.00",
  • "partner_salary": "string",
  • "partner_shareholding_percentage": "string",
  • "partner_self_employment_income": "string",
  • "partner_other_income": "string",
  • "partner_tax_code": "string",
  • "partner_personal_pension": "string",
  • "partner_charitable_donations": "string",
  • "children": [
    ],
  • "claims_child_benefit": false,
  • "total_dividends": "string",
  • "retain_this_year": "string"
}

api_calculator_contractor_user_create

Calculate contractor results using saved settings with overrides.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
annual_revenue
required
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

Annual company revenue

business_expenses
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"

Annual deductible business expenses

retained_profits
string <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
Default: "0.00"

Retained profits from prior years

total_pension_contribution
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"

Employer pension contribution

eligible_for_employment_allowance
boolean
Default: false
associated_companies
integer >= 0
Default: 0
vat_registered
boolean
Default: false
vat_using_flat_rate_scheme
boolean
Default: false
vat_flat_rate_percentage
string or null <decimal> ^-?\d{0,2}(?:\.\d{0,2})?$
quarterly_goods_cost
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
director_salary
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Director salary (e.g. £12,570)

director_shareholding_percentage
string <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$
Default: "100.00"
director_self_employment_income
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
director_other_income
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
director_tax_code
string <= 20 characters
Default: "1257L"
director_personal_pension
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
director_charitable_donations
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
partner_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_shareholding_percentage
string or null <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$
partner_self_employment_income
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_other_income
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_tax_code
string or null <= 20 characters
partner_personal_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
partner_charitable_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Array of objects (ChildInput)
claims_child_benefit
boolean
Default: false
total_dividends
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
retain_this_year
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$

Responses

Request samples

Content type
{
  • "annual_revenue": "string",
  • "business_expenses": "0.00",
  • "retained_profits": "0.00",
  • "total_pension_contribution": "0.00",
  • "eligible_for_employment_allowance": false,
  • "associated_companies": 0,
  • "vat_registered": false,
  • "vat_using_flat_rate_scheme": false,
  • "vat_flat_rate_percentage": "string",
  • "quarterly_goods_cost": "string",
  • "director_salary": "string",
  • "director_shareholding_percentage": "100.00",
  • "director_self_employment_income": "0.00",
  • "director_other_income": "0.00",
  • "director_tax_code": "1257L",
  • "director_personal_pension": "0.00",
  • "director_charitable_donations": "0.00",
  • "partner_salary": "string",
  • "partner_shareholding_percentage": "string",
  • "partner_self_employment_income": "string",
  • "partner_other_income": "string",
  • "partner_tax_code": "string",
  • "partner_personal_pension": "string",
  • "partner_charitable_donations": "string",
  • "children": [
    ],
  • "claims_child_benefit": false,
  • "total_dividends": "string",
  • "retain_this_year": "string"
}

api_entries_contributions_create

Create or delete a manual contribution entry (pension or charity).

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
date
required
string <date>

Date of contribution

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

contribution_type
required
string
Enum: "pension" "charity"

Type of contribution (pension or charity)

  • pension - Pension
  • charity - Charity
payment_method
required
string
Enum: "relief_at_source" "salary_sacrifice" "net_pay"

How the contribution was paid

  • relief_at_source - Relief at Source
  • salary_sacrifice - Salary Sacrifice
  • net_pay - Net Pay

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string",
  • "contribution_type": "pension",
  • "payment_method": "relief_at_source"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string",
  • "contribution_type": "pension",
  • "payment_method": "relief_at_source"
}

api_entries_contributions_destroy

Create or delete a manual contribution entry (pension or charity).

Authorizations:
cookieAuthbasicAuth

Responses

api_entries_contributions_create_2

Create or delete a manual contribution entry (pension or charity).

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>
Request Body schema:
required
date
required
string <date>

Date of contribution

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

contribution_type
required
string
Enum: "pension" "charity"

Type of contribution (pension or charity)

  • pension - Pension
  • charity - Charity
payment_method
required
string
Enum: "relief_at_source" "salary_sacrifice" "net_pay"

How the contribution was paid

  • relief_at_source - Relief at Source
  • salary_sacrifice - Salary Sacrifice
  • net_pay - Net Pay

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string",
  • "contribution_type": "pension",
  • "payment_method": "relief_at_source"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string",
  • "contribution_type": "pension",
  • "payment_method": "relief_at_source"
}

api_entries_contributions_destroy_2

Create or delete a manual contribution entry (pension or charity).

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>

Responses

api_entries_income_create

Create or delete a manual income entry.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
date
required
string <date>

Date of income

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string"
}

api_entries_income_destroy

Create or delete a manual income entry.

Authorizations:
cookieAuthbasicAuth

Responses

api_entries_income_tax_create

Create or delete a manual income tax entry.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
date
required
string <date>

Date of tax payment

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string"
}

api_entries_income_tax_destroy

Create or delete a manual income tax entry.

Authorizations:
cookieAuthbasicAuth

Responses

api_entries_income_tax_create_2

Create or delete a manual income tax entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>
Request Body schema:
required
date
required
string <date>

Date of tax payment

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string"
}

api_entries_income_tax_destroy_2

Create or delete a manual income tax entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>

Responses

api_entries_income_create_2

Create or delete a manual income entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>
Request Body schema:
required
date
required
string <date>

Date of income

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string"
}

api_entries_income_destroy_2

Create or delete a manual income entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>

Responses

api_entries_national_insurance_create

Create or delete a manual national insurance entry.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
date
required
string <date>

Date of NI contribution

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string"
}

api_entries_national_insurance_destroy

Create or delete a manual national insurance entry.

Authorizations:
cookieAuthbasicAuth

Responses

api_entries_national_insurance_create_2

Create or delete a manual national insurance entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>
Request Body schema:
required
date
required
string <date>

Date of NI contribution

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string"
}

api_entries_national_insurance_destroy_2

Create or delete a manual national insurance entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>

Responses

api_entries_taxable_benefits_create

Create or delete a manual taxable benefit entry.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
date
required
string <date>

Date of benefit

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

description
required
string <= 200 characters

Description of the benefit (e.g., 'Company car', 'Private medical')

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string",
  • "description": "string"
}

api_entries_taxable_benefits_destroy

Create or delete a manual taxable benefit entry.

Authorizations:
cookieAuthbasicAuth

Responses

api_entries_taxable_benefits_create_2

Create or delete a manual taxable benefit entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>
Request Body schema:
required
date
required
string <date>

Date of benefit

amount
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Amount in GBP

description
required
string <= 200 characters

Description of the benefit (e.g., 'Company car', 'Private medical')

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "amount": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24",
  • "amount": "string",
  • "description": "string"
}

api_entries_taxable_benefits_destroy_2

Create or delete a manual taxable benefit entry.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>

Responses

api_household_retrieve

Retrieve or update user settings for the authenticated user.

GET: Returns user settings data with household information POST/PUT/PATCH: Update user settings (gross_salary, partner, children, etc.) DELETE: Delete all household data (partner, children, tax years)

Authorizations:
cookieAuthbasicAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_payroll_giving_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

api_household_create

Handle POST requests (same as PUT for household endpoint compatibility).

Authorizations:
cookieAuthbasicAuth
Request Body schema:
primary_tax_code
string or null

Primary user's tax code

primary_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected annual gross salary (user's plan for tax optimisation)

primary_pension_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected pension contribution (user's plan for tax optimisation)

(PrimaryPensionContributionUnitB2eEnum (string or null)) or (NullEnum (any or null))

Whether pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
(PrimaryPensionContributionTypeBabEnum (string or null)) or (NullEnum (any or null))

Type of pension contribution

  • relief_at_source - Relief at Source
  • salary_sacrifice - Salary Sacrifice
  • net_pay - Net Pay
primary_employer_pension_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected employer pension contribution

(PrimaryEmployerPensionContributionUnitB2eEnum (string or null)) or (NullEnum (any or null))

Whether employer pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
primary_charity_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected charity contribution

(PrimaryCharityContributionTypeEnum (string or null)) or (NullEnum (any or null))

Type of charity contribution

  • gift_aid - Gift Aid
  • payroll_giving - Payroll Giving
partner_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected gross salary

partner_net_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected pension contributions

(PartnerNetPensionContributionsTypeB2eEnum (string or null)) or (NullEnum (any or null))

Whether partner pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
partner_employer_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected employer pension contributions

(PartnerEmployerPensionContributionsTypeB2eEnum (string or null)) or (NullEnum (any or null))

Whether partner employer pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
partner_gift_aid_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected Gift Aid donations

partner_tax_code
string or null

Partner's tax code (null if no partner)

object or null

Partner information (editable)

Array of objects (Child)

Children (editable)

claims_child_benefit
boolean

Whether child benefit is claimed

preferred_strategy
string or null

Preferred tax optimisation strategy

payslip_reminder_day
integer or null [ 1 .. 31 ]

Day of month for payslip reminders (1-31). Null to disable.

Responses

Request samples

Content type
{
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_payroll_giving_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

api_household_update

Retrieve or update user settings for the authenticated user.

GET: Returns user settings data with household information POST/PUT/PATCH: Update user settings (gross_salary, partner, children, etc.) DELETE: Delete all household data (partner, children, tax years)

Authorizations:
cookieAuthbasicAuth
Request Body schema:
primary_tax_code
string or null

Primary user's tax code

primary_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected annual gross salary (user's plan for tax optimisation)

primary_pension_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected pension contribution (user's plan for tax optimisation)

(PrimaryPensionContributionUnitB2eEnum (string or null)) or (NullEnum (any or null))

Whether pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
(PrimaryPensionContributionTypeBabEnum (string or null)) or (NullEnum (any or null))

Type of pension contribution

  • relief_at_source - Relief at Source
  • salary_sacrifice - Salary Sacrifice
  • net_pay - Net Pay
primary_employer_pension_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected employer pension contribution

(PrimaryEmployerPensionContributionUnitB2eEnum (string or null)) or (NullEnum (any or null))

Whether employer pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
primary_charity_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected charity contribution

(PrimaryCharityContributionTypeEnum (string or null)) or (NullEnum (any or null))

Type of charity contribution

  • gift_aid - Gift Aid
  • payroll_giving - Payroll Giving
partner_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected gross salary

partner_net_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected pension contributions

(PartnerNetPensionContributionsTypeB2eEnum (string or null)) or (NullEnum (any or null))

Whether partner pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
partner_employer_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected employer pension contributions

(PartnerEmployerPensionContributionsTypeB2eEnum (string or null)) or (NullEnum (any or null))

Whether partner employer pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
partner_gift_aid_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected Gift Aid donations

partner_tax_code
string or null

Partner's tax code (null if no partner)

object or null

Partner information (editable)

Array of objects (Child)

Children (editable)

claims_child_benefit
boolean

Whether child benefit is claimed

preferred_strategy
string or null

Preferred tax optimisation strategy

payslip_reminder_day
integer or null [ 1 .. 31 ]

Day of month for payslip reminders (1-31). Null to disable.

Responses

Request samples

Content type
{
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_payroll_giving_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

api_household_partial_update

Retrieve or update user settings for the authenticated user.

GET: Returns user settings data with household information POST/PUT/PATCH: Update user settings (gross_salary, partner, children, etc.) DELETE: Delete all household data (partner, children, tax years)

Authorizations:
cookieAuthbasicAuth
Request Body schema:
primary_tax_code
string or null

Primary user's tax code

primary_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected annual gross salary (user's plan for tax optimisation)

primary_pension_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected pension contribution (user's plan for tax optimisation)

(PrimaryPensionContributionUnitB2eEnum (string or null)) or (NullEnum (any or null))

Whether pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
(PrimaryPensionContributionTypeBabEnum (string or null)) or (NullEnum (any or null))

Type of pension contribution

  • relief_at_source - Relief at Source
  • salary_sacrifice - Salary Sacrifice
  • net_pay - Net Pay
primary_employer_pension_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected employer pension contribution

(PrimaryEmployerPensionContributionUnitB2eEnum (string or null)) or (NullEnum (any or null))

Whether employer pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
primary_charity_contribution
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Expected charity contribution

(PrimaryCharityContributionTypeEnum (string or null)) or (NullEnum (any or null))

Type of charity contribution

  • gift_aid - Gift Aid
  • payroll_giving - Payroll Giving
partner_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected gross salary

partner_net_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected pension contributions

(PartnerNetPensionContributionsTypeB2eEnum (string or null)) or (NullEnum (any or null))

Whether partner pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
partner_employer_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected employer pension contributions

(PartnerEmployerPensionContributionsTypeB2eEnum (string or null)) or (NullEnum (any or null))

Whether partner employer pension contribution is amount or percentage

  • amount - Amount
  • percentage - Percentage
partner_gift_aid_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Partner's expected Gift Aid donations

partner_tax_code
string or null

Partner's tax code (null if no partner)

object or null

Partner information (editable)

Array of objects (Child)

Children (editable)

claims_child_benefit
boolean

Whether child benefit is claimed

preferred_strategy
string or null

Preferred tax optimisation strategy

payslip_reminder_day
integer or null [ 1 .. 31 ]

Day of month for payslip reminders (1-31). Null to disable.

Responses

Request samples

Content type
{
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
  • "primary_tax_code": "string",
  • "primary_gross_salary": "string",
  • "primary_pension_contribution": "string",
  • "primary_pension_contribution_unit": "amount",
  • "primary_pension_contribution_type": "relief_at_source",
  • "primary_employer_pension_contribution": "string",
  • "primary_employer_pension_contribution_unit": "amount",
  • "primary_charity_contribution": "string",
  • "primary_charity_contribution_type": "gift_aid",
  • "partner_gross_salary": "string",
  • "partner_net_pension_contributions": "string",
  • "partner_net_pension_contributions_type": "amount",
  • "partner_employer_pension_contributions": "string",
  • "partner_employer_pension_contributions_type": "amount",
  • "partner_gift_aid_donations": "string",
  • "partner_payroll_giving_donations": "string",
  • "partner_tax_code": "string",
  • "partner": {
    },
  • "children": [
    ],
  • "claims_child_benefit": true,
  • "preferred_strategy": "string",
  • "payslip_reminder_day": 1,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

api_household_destroy

Delete all household data for the user.

Deletes:

  • Partner
  • Children
  • All tax years (which cascades to Income, Contributions, etc.)
  • Does NOT delete User account
Authorizations:
cookieAuthbasicAuth

Responses

api_payslips_create

Create or delete a payslip with all related entries.

POST: Creates a Payslip object and all related Income, IncomeTax, NationalInsurance, and optionally Contribution entries in a single database transaction. DELETE: Deletes a payslip and all related entries (via cascade).

This ensures data integrity - either all entries are created/deleted successfully, or none are created/deleted if any validation fails.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
date
required
string <date>

Date of the payslip

gross_salary
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Gross salary amount in GBP

tax
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Income tax amount in GBP

national_insurance
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

National Insurance amount in GBP

pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Pension contribution amount in GBP

(PensionMethodEnum (string or null)) or (NullEnum (any or null))
Default: "relief_at_source"

Payment method for pension (relief_at_source or salary_sacrifice)

  • relief_at_source - relief_at_source
  • salary_sacrifice - salary_sacrifice
charity
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Charity contribution amount in GBP

(CharityMethodEnum (string or null)) or (NullEnum (any or null))
Default: "relief_at_source"

Payment method for charity (relief_at_source or salary_sacrifice)

  • relief_at_source - relief_at_source
  • salary_sacrifice - salary_sacrifice

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "gross_salary": "string",
  • "tax": "string",
  • "national_insurance": "string",
  • "pension": "string",
  • "pension_method": "relief_at_source",
  • "charity": "string",
  • "charity_method": "relief_at_source"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24"
}

api_payslips_destroy

Create or delete a payslip with all related entries.

POST: Creates a Payslip object and all related Income, IncomeTax, NationalInsurance, and optionally Contribution entries in a single database transaction. DELETE: Deletes a payslip and all related entries (via cascade).

This ensures data integrity - either all entries are created/deleted successfully, or none are created/deleted if any validation fails.

Authorizations:
cookieAuthbasicAuth

Responses

api_payslips_create_2

Create or delete a payslip with all related entries.

POST: Creates a Payslip object and all related Income, IncomeTax, NationalInsurance, and optionally Contribution entries in a single database transaction. DELETE: Deletes a payslip and all related entries (via cascade).

This ensures data integrity - either all entries are created/deleted successfully, or none are created/deleted if any validation fails.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>
Request Body schema:
required
date
required
string <date>

Date of the payslip

gross_salary
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Gross salary amount in GBP

tax
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Income tax amount in GBP

national_insurance
required
string <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

National Insurance amount in GBP

pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Pension contribution amount in GBP

(PensionMethodEnum (string or null)) or (NullEnum (any or null))
Default: "relief_at_source"

Payment method for pension (relief_at_source or salary_sacrifice)

  • relief_at_source - relief_at_source
  • salary_sacrifice - salary_sacrifice
charity
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$

Charity contribution amount in GBP

(CharityMethodEnum (string or null)) or (NullEnum (any or null))
Default: "relief_at_source"

Payment method for charity (relief_at_source or salary_sacrifice)

  • relief_at_source - relief_at_source
  • salary_sacrifice - salary_sacrifice

Responses

Request samples

Content type
{
  • "date": "2019-08-24",
  • "gross_salary": "string",
  • "tax": "string",
  • "national_insurance": "string",
  • "pension": "string",
  • "pension_method": "relief_at_source",
  • "charity": "string",
  • "charity_method": "relief_at_source"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "date": "2019-08-24"
}

api_payslips_destroy_2

Create or delete a payslip with all related entries.

POST: Creates a Payslip object and all related Income, IncomeTax, NationalInsurance, and optionally Contribution entries in a single database transaction. DELETE: Deletes a payslip and all related entries (via cascade).

This ensures data integrity - either all entries are created/deleted successfully, or none are created/deleted if any validation fails.

Authorizations:
cookieAuthbasicAuth
path Parameters
external_id
required
string <uuid>

Responses

api_payslips_tasks_retrieve

Get task status by task_id.

Authorizations:
cookieAuthbasicAuth
path Parameters
task_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  • "status": "pending"
}

api_payslips_upload_create

Handle payslip file upload and dispatch processing task.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
required
file
required
string <uri>

Payslip file (PDF or image: png, jpg, jpeg, gif, webp)

Responses

Response samples

Content type
application/json
{}

api_schema_retrieve

OpenApi3 schema for this API. Format can be selected via content negotiation.

  • YAML: application/vnd.oai.openapi
  • JSON: application/vnd.oai.openapi+json
Authorizations:
cookieAuthbasicAuthNone
query Parameters
format
string
Enum: "json" "yaml"
lang
string
Enum: "af" "ar" "ar-dz" "ast" "az" "be" "bg" "bn" "br" "bs" "ca" "ckb" "cs" "cy" "da" "de" "dsb" "el" "en" "en-au" "en-gb" "eo" "es" "es-ar" "es-co" "es-mx" "es-ni" "es-ve" "et" "eu" "fa" "fi" "fr" "fy" "ga" "gd" "gl" "he" "hi" "hr" "hsb" "hu" "hy" "ia" "id" "ig" "io" "is" "it" "ja" "ka" "kab" "kk" "km" "kn" "ko" "ky" "lb" "lt" "lv" "mk" "ml" "mn" "mr" "ms" "my" "nb" "ne" "nl" "nn" "os" "pa" "pl" "pt" "pt-br" "ro" "ru" "sk" "sl" "sq" "sr" "sr-latn" "sv" "sw" "ta" "te" "tg" "th" "tk" "tr" "tt" "udm" "ug" "uk" "ur" "uz" "vi" "zh-hans" "zh-hant"

Responses

Response samples

Content type
No sample

api_settings_contractor_retrieve

Contractor expected values stored on the current tax year.

Authorizations:
cookieAuthbasicAuth

Responses

Response samples

Content type
application/json
{
  • "expected_contractor_revenue": "string",
  • "expected_contractor_expenses": "3000.00",
  • "expected_contractor_retained_profits": "0.00",
  • "expected_contractor_director_salary": "string",
  • "expected_contractor_partner_salary": "string",
  • "expected_contractor_company_pension": "0.00",
  • "expected_contractor_director_personal_pension": "0.00",
  • "expected_contractor_partner_personal_pension": "0.00"
}

api_settings_contractor_update

Contractor expected values stored on the current tax year.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
expected_contractor_revenue
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
expected_contractor_expenses
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "3000.00"
expected_contractor_retained_profits
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
Default: "0.00"
expected_contractor_director_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
expected_contractor_partner_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
expected_contractor_company_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
expected_contractor_director_personal_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
expected_contractor_partner_personal_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"

Responses

Request samples

Content type
{
  • "expected_contractor_revenue": "string",
  • "expected_contractor_expenses": "3000.00",
  • "expected_contractor_retained_profits": "0.00",
  • "expected_contractor_director_salary": "string",
  • "expected_contractor_partner_salary": "string",
  • "expected_contractor_company_pension": "0.00",
  • "expected_contractor_director_personal_pension": "0.00",
  • "expected_contractor_partner_personal_pension": "0.00"
}

Response samples

Content type
application/json
{
  • "expected_contractor_revenue": "string",
  • "expected_contractor_expenses": "3000.00",
  • "expected_contractor_retained_profits": "0.00",
  • "expected_contractor_director_salary": "string",
  • "expected_contractor_partner_salary": "string",
  • "expected_contractor_company_pension": "0.00",
  • "expected_contractor_director_personal_pension": "0.00",
  • "expected_contractor_partner_personal_pension": "0.00"
}

api_settings_contractor_partial_update

Contractor expected values stored on the current tax year.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
expected_contractor_revenue
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
expected_contractor_expenses
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "3000.00"
expected_contractor_retained_profits
string or null <decimal> ^-?\d{0,10}(?:\.\d{0,2})?$
Default: "0.00"
expected_contractor_director_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
expected_contractor_partner_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
expected_contractor_company_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
expected_contractor_director_personal_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"
expected_contractor_partner_personal_pension
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
Default: "0.00"

Responses

Request samples

Content type
{
  • "expected_contractor_revenue": "string",
  • "expected_contractor_expenses": "3000.00",
  • "expected_contractor_retained_profits": "0.00",
  • "expected_contractor_director_salary": "string",
  • "expected_contractor_partner_salary": "string",
  • "expected_contractor_company_pension": "0.00",
  • "expected_contractor_director_personal_pension": "0.00",
  • "expected_contractor_partner_personal_pension": "0.00"
}

Response samples

Content type
application/json
{
  • "expected_contractor_revenue": "string",
  • "expected_contractor_expenses": "3000.00",
  • "expected_contractor_retained_profits": "0.00",
  • "expected_contractor_director_salary": "string",
  • "expected_contractor_partner_salary": "string",
  • "expected_contractor_company_pension": "0.00",
  • "expected_contractor_director_personal_pension": "0.00",
  • "expected_contractor_partner_personal_pension": "0.00"
}

api_settings_contractor_profile_retrieve

Contractor structural setup including VAT and shareholding.

Authorizations:
cookieAuthbasicAuth

Responses

Response samples

Content type
application/json
{
  • "ir35_status": "outside",
  • "vat_registered": true,
  • "vat_using_flat_rate_scheme": true,
  • "vat_flat_rate_percentage": "string",
  • "director_shareholding_percentage": "string",
  • "partner_shareholding_percentage": "string",
  • "eligible_for_employment_allowance": true,
  • "associated_companies": -2147483648
}

api_settings_contractor_profile_update

Contractor structural setup including VAT and shareholding.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
ir35_status
string
Value: "outside"

IR35 status: only outside IR35 is supported (calculator provides dividend optimisation strategies)

  • outside - Outside IR35 (genuine contractor)
vat_registered
boolean

Whether company is VAT registered (required if turnover >£90k)

vat_using_flat_rate_scheme
boolean

Whether using VAT Flat Rate Scheme (simplified VAT)

vat_flat_rate_percentage
string or null <decimal> ^-?\d{0,2}(?:\.\d{0,2})?$

Effective FRS percentage you will use (after any discounts/penalties). Examples: 14.5% (standard IT), 13.5% (first year IT), 16.5% (LCT), 15.5% (first year + LCT)

director_shareholding_percentage
string <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$

Director shareholding percentage (0-100)

partner_shareholding_percentage
string or null <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$

Partner shareholding percentage (must sum to 100 with director)

eligible_for_employment_allowance
boolean

Whether eligible for Employment Allowance (£10,500 for 2025/26). Requirements: (1) At least one other employee/director on payroll besides yourself, AND (2) At least one person earning above secondary threshold (£5,000 for 2025/26) to create employer NI liability. Example: Director + partner both earning £12,570 = eligible. Director alone (even at £12,570) = NOT eligible.

associated_companies
integer [ -2147483648 .. 2147483647 ]

Number of associated companies (affects corporation tax thresholds). Thresholds divided by (1 + associated companies). E.g., 1 associated company: £25k-£125k marginal relief band.

Responses

Request samples

Content type
{
  • "ir35_status": "outside",
  • "vat_registered": true,
  • "vat_using_flat_rate_scheme": true,
  • "vat_flat_rate_percentage": "string",
  • "director_shareholding_percentage": "string",
  • "partner_shareholding_percentage": "string",
  • "eligible_for_employment_allowance": true,
  • "associated_companies": -2147483648
}

Response samples

Content type
application/json
{
  • "ir35_status": "outside",
  • "vat_registered": true,
  • "vat_using_flat_rate_scheme": true,
  • "vat_flat_rate_percentage": "string",
  • "director_shareholding_percentage": "string",
  • "partner_shareholding_percentage": "string",
  • "eligible_for_employment_allowance": true,
  • "associated_companies": -2147483648
}

api_settings_contractor_profile_partial_update

Contractor structural setup including VAT and shareholding.

Authorizations:
cookieAuthbasicAuth
Request Body schema:
ir35_status
string
Value: "outside"

IR35 status: only outside IR35 is supported (calculator provides dividend optimisation strategies)

  • outside - Outside IR35 (genuine contractor)
vat_registered
boolean

Whether company is VAT registered (required if turnover >£90k)

vat_using_flat_rate_scheme
boolean

Whether using VAT Flat Rate Scheme (simplified VAT)

vat_flat_rate_percentage
string or null <decimal> ^-?\d{0,2}(?:\.\d{0,2})?$

Effective FRS percentage you will use (after any discounts/penalties). Examples: 14.5% (standard IT), 13.5% (first year IT), 16.5% (LCT), 15.5% (first year + LCT)

director_shareholding_percentage
string <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$

Director shareholding percentage (0-100)

partner_shareholding_percentage
string or null <decimal> ^-?\d{0,3}(?:\.\d{0,2})?$

Partner shareholding percentage (must sum to 100 with director)

eligible_for_employment_allowance
boolean

Whether eligible for Employment Allowance (£10,500 for 2025/26). Requirements: (1) At least one other employee/director on payroll besides yourself, AND (2) At least one person earning above secondary threshold (£5,000 for 2025/26) to create employer NI liability. Example: Director + partner both earning £12,570 = eligible. Director alone (even at £12,570) = NOT eligible.

associated_companies
integer [ -2147483648 .. 2147483647 ]

Number of associated companies (affects corporation tax thresholds). Thresholds divided by (1 + associated companies). E.g., 1 associated company: £25k-£125k marginal relief band.

Responses

Request samples

Content type
{
  • "ir35_status": "outside",
  • "vat_registered": true,
  • "vat_using_flat_rate_scheme": true,
  • "vat_flat_rate_percentage": "string",
  • "director_shareholding_percentage": "string",
  • "partner_shareholding_percentage": "string",
  • "eligible_for_employment_allowance": true,
  • "associated_companies": -2147483648
}

Response samples

Content type
application/json
{
  • "ir35_status": "outside",
  • "vat_registered": true,
  • "vat_using_flat_rate_scheme": true,
  • "vat_flat_rate_percentage": "string",
  • "director_shareholding_percentage": "string",
  • "partner_shareholding_percentage": "string",
  • "eligible_for_employment_allowance": true,
  • "associated_companies": -2147483648
}

api_tax_years_list

ViewSet for managing tax years with full CRUD operations.

Endpoints:

  • GET /api/tax-years/ - List all tax years
  • POST /api/tax-years/ - Create a new tax year
  • GET /api/tax-years/{year_label}/ - Retrieve a specific tax year
  • PATCH /api/tax-years/{year_label}/ - Partially update a tax year
  • DELETE /api/tax-years/{year_label}/ - Delete a tax year
  • GET /api/tax-years/current/ - Get or create current tax year (custom action)

Note: PUT is not supported. Use PATCH for partial updates.

Authorizations:
cookieAuthbasicAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

api_tax_years_create

ViewSet for managing tax years with full CRUD operations.

Endpoints:

  • GET /api/tax-years/ - List all tax years
  • POST /api/tax-years/ - Create a new tax year
  • GET /api/tax-years/{year_label}/ - Retrieve a specific tax year
  • PATCH /api/tax-years/{year_label}/ - Partially update a tax year
  • DELETE /api/tax-years/{year_label}/ - Delete a tax year
  • GET /api/tax-years/current/ - Get or create current tax year (custom action)

Note: PUT is not supported. Use PATCH for partial updates.

Authorizations:
cookieAuthbasicAuth
Request Body schema:

Responses

Request samples

Content type
{ }

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "year_label": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "expected_gross_salary": "string",
  • "claims_child_benefit": true,
  • "income_entries": [
    ],
  • "contribution_entries": [
    ],
  • "income_tax_entries": [
    ],
  • "national_insurance_entries": [
    ],
  • "taxable_benefit_entries": [
    ],
  • "monthly_breakdown": [
    ],
  • "aggregates": {
    },
  • "projections": {
    }
}

api_tax_years_retrieve

ViewSet for managing tax years with full CRUD operations.

Endpoints:

  • GET /api/tax-years/ - List all tax years
  • POST /api/tax-years/ - Create a new tax year
  • GET /api/tax-years/{year_label}/ - Retrieve a specific tax year
  • PATCH /api/tax-years/{year_label}/ - Partially update a tax year
  • DELETE /api/tax-years/{year_label}/ - Delete a tax year
  • GET /api/tax-years/current/ - Get or create current tax year (custom action)

Note: PUT is not supported. Use PATCH for partial updates.

Authorizations:
cookieAuthbasicAuth
path Parameters
year_label
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "year_label": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "expected_gross_salary": "string",
  • "claims_child_benefit": true,
  • "income_entries": [
    ],
  • "contribution_entries": [
    ],
  • "income_tax_entries": [
    ],
  • "national_insurance_entries": [
    ],
  • "taxable_benefit_entries": [
    ],
  • "monthly_breakdown": [
    ],
  • "aggregates": {
    },
  • "projections": {
    }
}

api_tax_years_partial_update

ViewSet for managing tax years with full CRUD operations.

Endpoints:

  • GET /api/tax-years/ - List all tax years
  • POST /api/tax-years/ - Create a new tax year
  • GET /api/tax-years/{year_label}/ - Retrieve a specific tax year
  • PATCH /api/tax-years/{year_label}/ - Partially update a tax year
  • DELETE /api/tax-years/{year_label}/ - Delete a tax year
  • GET /api/tax-years/current/ - Get or create current tax year (custom action)

Note: PUT is not supported. Use PATCH for partial updates.

Authorizations:
cookieAuthbasicAuth
path Parameters
year_label
required
string
Request Body schema:
primary_gross_salary
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
primary_net_pension_contributions
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
primary_charitable_donations
string or null <decimal> ^-?\d{0,8}(?:\.\d{0,2})?$
claims_child_benefit
boolean

Whether child benefit is claimed for this tax year

Responses

Request samples

Content type
{
  • "primary_gross_salary": "string",
  • "primary_net_pension_contributions": "string",
  • "primary_charitable_donations": "string",
  • "claims_child_benefit": true
}

Response samples

Content type
application/json
{
  • "primary_gross_salary": "string",
  • "primary_net_pension_contributions": "string",
  • "primary_charitable_donations": "string",
  • "claims_child_benefit": true
}

api_tax_years_destroy

ViewSet for managing tax years with full CRUD operations.

Endpoints:

  • GET /api/tax-years/ - List all tax years
  • POST /api/tax-years/ - Create a new tax year
  • GET /api/tax-years/{year_label}/ - Retrieve a specific tax year
  • PATCH /api/tax-years/{year_label}/ - Partially update a tax year
  • DELETE /api/tax-years/{year_label}/ - Delete a tax year
  • GET /api/tax-years/current/ - Get or create current tax year (custom action)

Note: PUT is not supported. Use PATCH for partial updates.

Authorizations:
cookieAuthbasicAuth
path Parameters
year_label
required
string

Responses

api_tax_years_current_retrieve

Get or create the current tax year.

GET /api/tax-years/current/ - Returns current tax year with all entries

⚠️ WARNING: This endpoint creates a tax year if it doesn't exist, violating REST idempotency. This is intentional for UX - users shouldn't need a separate POST to create their current tax year.

Authorizations:
cookieAuthbasicAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "year_label": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "expected_gross_salary": "string",
  • "claims_child_benefit": true,
  • "income_entries": [
    ],
  • "contribution_entries": [
    ],
  • "income_tax_entries": [
    ],
  • "national_insurance_entries": [
    ],
  • "taxable_benefit_entries": [
    ],
  • "monthly_breakdown": [
    ],
  • "aggregates": {
    },
  • "projections": {
    }
}

api_tracker_retrieve

Get consolidated tracker data for current tax year.

Authorizations:
cookieAuthbasicAuth

Responses

Response samples

Content type
application/json
{
  • "label": "string",
  • "start_date": "2019-08-24",
  • "end_date": "2019-08-24",
  • "current_month": "string",
  • "current_month_index": 0,
  • "completed_months": 0,
  • "months_remaining": 0,
  • "expected_income": "string",
  • "pension_contributions_to_date": "string",
  • "charitable_contributions_to_date": "string",
  • "has_children": true,
  • "projected_adjusted_net_income": "string",
  • "projected_annual_tax": "string",
  • "target_annual_tax": "string",
  • "contribution_gauge": {
    },
  • "tax_savings_card": {
    },
  • "gross_income_block": {
    },
  • "monthly_table": {
    },
  • "entries": [
    ],
  • "cumulative_chart": {
    }
}

auth

auth_logout_create

Log out the current user by destroying their session. Returns 204 No Content on success (or redirects to home if from template).

Authorizations:
cookieAuthbasicAuth

Responses

auth_request_code_create

Request an authentication code to be sent via email. Creates a 6-character code and sends both magic link and code via email. Returns 204 No Content to avoid leaking whether email exists.

Rate limits:

  • 5 requests per hour per IP address
  • 3 requests per hour per email address
Authorizations:
cookieAuthbasicAuthNone
Request Body schema:
required
email
required
string <email>

Email address to send authentication code to

Responses

Request samples

Content type
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "email": "user@example.com"
}

auth_verify_create

Verify an authentication code and log the user in. Creates user account if it doesn't exist (passwordless signup). Returns 204 No Content on success with session cookie set.

Authorizations:
cookieAuthbasicAuthNone
Request Body schema:
required
email
required
string <email>

Email address the code was sent to

code
required
string = 6 characters

6-character authentication code

Responses

Request samples

Content type
{
  • "email": "user@example.com",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "email": "user@example.com",
  • "code": "string"
}

openapi.json

openapi.json_retrieve

OpenApi3 schema for this API. Format can be selected via content negotiation.

  • YAML: application/vnd.oai.openapi
  • JSON: application/vnd.oai.openapi+json
Authorizations:
cookieAuthbasicAuthNone
query Parameters
format
string
Enum: "json" "yaml"
lang
string
Enum: "af" "ar" "ar-dz" "ast" "az" "be" "bg" "bn" "br" "bs" "ca" "ckb" "cs" "cy" "da" "de" "dsb" "el" "en" "en-au" "en-gb" "eo" "es" "es-ar" "es-co" "es-mx" "es-ni" "es-ve" "et" "eu" "fa" "fi" "fr" "fy" "ga" "gd" "gl" "he" "hi" "hr" "hsb" "hu" "hy" "ia" "id" "ig" "io" "is" "it" "ja" "ka" "kab" "kk" "km" "kn" "ko" "ky" "lb" "lt" "lv" "mk" "ml" "mn" "mr" "ms" "my" "nb" "ne" "nl" "nn" "os" "pa" "pl" "pt" "pt-br" "ro" "ru" "sk" "sl" "sq" "sr" "sr-latn" "sv" "sw" "ta" "te" "tg" "th" "tk" "tr" "tt" "udm" "ug" "uk" "ur" "uz" "vi" "zh-hans" "zh-hant"

Responses

Response samples

Content type
No sample

v1

v1_subscriptions_checkout_create

Create a Stripe Checkout session for subscription.

Returns a checkout URL to redirect the user to Stripe's hosted checkout page. Creates a Stripe customer if one doesn't exist. Includes trial period.

Authorizations:
cookieAuth
Request Body schema:
required
price_id
required
string

Stripe price ID (price_xxx)

success_url
required
string <uri>

URL to redirect to after successful checkout

cancel_url
required
string <uri>

URL to redirect to if user cancels checkout

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{}

v1_subscriptions_portal_create

Create a Stripe Customer Portal session.

Returns a portal URL to redirect the user to Stripe's billing portal where they can manage their subscription (cancel, update payment, etc.)

Authorizations:
cookieAuth
Request Body schema:
return_url
string <uri>

URL to redirect to after leaving the portal

Responses

Request samples

Content type
{}

Response samples

Content type
application/json
{}

v1_subscriptions_sync_create

Sync subscription status from Stripe.

Called by frontend after returning from checkout to ensure subscription status is up-to-date without waiting for webhooks.

Authorizations:
cookieAuth

Responses

v1_subscriptions_webhook_create

Handle Stripe webhook events.

Verifies webhook signature and processes subscription events:

  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
Authorizations:
None

Responses