Questionnaire
The Questionnaire API provides access to the complete questionnaire structure used for Stamp Duty Land Tax (SDLT) calculations. This endpoint returns all questions, their response options, conditions, and helpful information.
The questionnaire structure
The questionnaire structure contains all the questions, response options, conditions, and helpful information needed to build dynamic forms for SDLT calculations.
Properties
- Name
ref- Type
- string
- Description
The unique reference identifier for the question. This is used to identify the question in API requests and responses.
- Name
question- Type
- string
- Description
The question text that will be displayed to users.
- Name
info- Type
- string
- Description
Helpful information and guidance for the question. Contains explanations, examples, and instructions.
- Name
responseType- Type
- string
- Description
The type of response expected. Values include: "text", "number", "select", "date", "radio_button", "currency".
- Name
responseOptions- Type
- array
- Description
Available options for select/radio button questions. Each option has a "name" (display text) and "value" (actual value). Null for text/number/date/currency inputs.
- Name
conditions- Type
- object
- Description
Conditions that determine when this question should be shown. Null means the question is always shown. Contains field references and expected values (e.g.,
{"is_leasehold": "YES"}). Questions with conditions are only shown when the condition is met.
The questionnaire response
The response will contain the complete questionnaire structure with all questions, their response options, and helpful information.
Properties
- Name
questionnaire- Type
- array
- Description
The complete questionnaire structure containing all questions with their properties, response options, and conditions.
Get questionnaire structure
This endpoint allows you to retrieve the complete questionnaire structure. To access the questionnaire, you must authenticate with the Stamp Expert API using an API key.
Required attributes
No request body is required for this endpoint. Authentication is handled via the Authorization header.
Optional attributes
No optional attributes are available for this endpoint.
Request
curl --request GET \
--url https://api.stamp.expert/v1/questionnaire/structure \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'User-Agent: insomnia/11.3.0'
Response
{
"questionnaire": [
{
"ref": "case_ref",
"question": "What is the property address or your reference?",
"info": "\nPlease enter the property address or reference. This is for your records so you can easily identify this calculation later.\n ",
"responseType": "text",
"responseOptions": null,
"conditions": null
},
{
"ref": "country",
"question": "Which country in the UK is the property located in?",
"info": "\nThis is the most important first step, as each UK country has its own property tax system. \nYour choice here determines which specific tax we need to calculate:\n- England & Northern Ireland: Stamp Duty Land Tax (SDLT)\n- Scotland: Land and Buildings Transaction Tax (LBTT)\n- Wales: Land Transaction Tax (LTT)\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "England & Northern Ireland", "value": "ENGLAND"},
{"name": "Wales", "value": "WALES"},
{"name": "Scotland", "value": "SCOTLAND"}
],
"conditions": null
},
{
"ref": "is_leasehold",
"question": "Is the property leasehold?",
"info": "\nLeasehold properties involve different Stamp Duty rules compared to freehold properties. \nThis is especially true for longer leases (over 7 years) and if any rent is payable over the life of the lease. \nThis helps us ensure your calculation is accurate for your specific type of ownership.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "lease_nature",
"question": "Which of these best describes your lease transaction?",
"info": "\nThe tax rules are different for brand new leases compared to transactions involving existing ones. \nExtending a lease or changing its terms can be treated by tax law as the termination ('surrender') of your old lease and \nthe creation ('regrant') of a completely new one. This triggers a complex calculation to ensure you're not taxed twice on \nthe same rent. \nTaking over an existing lease (an 'assignment') is taxed on the price you pay for it, similar to buying a freehold property, \nand follows a different set of rules.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "I am getting a brand new lease from the landlord.", "value": "NEW"},
{"name": "I am extending or changing my existing lease.", "value": "EXTENSION"},
{"name": "I am taking over a lease from someone else.", "value": "TAKEOVER"}
],
"conditions": {"is_leasehold": "YES"}
},
{
"ref": "lease_type",
"question": "How will you be paying for the lease?",
"info": "\nThis question helps us understand two critical things. \n- First, it confirms you are paying a regular rent, which is taxed based on its Net Present Value (NPV), rather than a one-off lump sum (a premium), which is taxed differently.\n- Second, it confirms the rent amount is certain. If the rent can change or is uncertain in the first five years (e.g., it's linked to business turnover), the law requires an initial tax payment based on a \"reasonable estimate,\" followed by a mandatory recalculation and a second tax return in the future. \nThis two-stage process requires specialist advice. Some leases involve both, if so, we will ask about that later.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "With regular rent payments.", "value": "RENT"},
{"name": "With a one-off upfront payment (a 'premium').", "value": "PREMIUM"}
],
"conditions": {"is_leasehold": "YES"}
},
{
"ref": "lease_premium",
"question": "What is the total premium payable for the lease?",
"info": "\nThe SDLT on a lease is made up of two parts. This first part is the tax on the premium (the upfront lump sum). \nIt is calculated using the same tax bands as a freehold property purchase. We need to know the full amount, including any VAT, as VAT forms part of the taxable consideration.\n ",
"responseType": "currency",
"responseOptions": null,
"conditions": {"is_leasehold": "YES", "lease_type": "PREMIUM"}
},
{
"ref": "lease_term",
"question": "What is the term of the lease in years?",
"info": "\nThis is for the second part of the SDLT calculation, which is the tax on the rent. \nWe calculate the Net Present Value (NPV) of all rental payments over the full term of the lease.\nThe rent figures for the first five years are the foundation of this calculation. \nFor leases longer than five years, the single highest rent from this initial period is used for all subsequent years. \nWe must include any VAT payable on the rent in these figures.\n ",
"responseType": "number",
"responseOptions": null,
"conditions": {"is_leasehold": "YES", "lease_type": "RENT"}
},
{
"ref": "lease_rent_year_1",
"question": "What is the rent payable for the first year?",
"info": "\nThis is for the second part of the SDLT calculation, which is the tax on the rent. \nWe calculate the Net Present Value (NPV) of all rental payments over the full term of the lease.\nThe rent figures for the first five years are the foundation of this calculation. \nFor leases longer than five years, the single highest rent from this initial period is used for all subsequent years. \nWe must include any VAT payable on the rent in these figures.\n ",
"responseType": "currency",
"responseOptions": null,
"conditions": {"is_leasehold": "YES", "lease_type": "RENT"}
},
{
"ref": "property_value",
"question": "What is the property's purchase price?",
"info": "\n The Stamp Duty is calculated based on the price you are paying for the property (this is known as the 'chargeable consideration')\n ",
"responseType": "currency",
"responseOptions": null,
"conditions": {"is_leasehold": "NO"}
},
{
"ref": "completion_date",
"question": "What is the estimated completion date for your purchase?",
"info": "\nThe completion date is very important because Stamp Duty rules and rates can change over time. \nUsing your estimated date ensures the calculation is based on the correct tax rules that will be in effect when you buy your property. \nDon't worry if you don't have a fixed date yet; please provide your best estimate. \nThis allows the calculation to account for any announced changes from government Budgets. \nIf your completion date moves significantly, the calculation may need to be revisited.\n ",
"responseType": "date",
"responseOptions": null,
"conditions": null
},
{
"ref": "is_refinance",
"question": "Are you adding or removing someone from your existing property's title deeds?",
"info": "\nChanging the legal owners of a property (an action often called a 'Transfer of Equity') can sometimes trigger a Stamp Duty payment, \nespecially when a mortgage is involved. This is common for scenarios like:\n- Buying out an ex-partner.\n- Being gifted a share of a property that has a mortgage.\n- Adding a new partner to the deeds where they take on part of the mortgage debt.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": {"is_leasehold": "NO"}
},
{
"ref": "buyer_type",
"question": "Who will be buying this property?",
"info": "\nThe type of buyer can significantly change how your Stamp Duty is calculated and what rates apply. \nFor example, individuals buying their main home have different rules than companies, trusts, or those purchasing properties as a couple.\n ",
"responseType": "select",
"responseOptions": [
{"name": "Individual", "value": "INDIVIDUAL"},
{"name": "Couple", "value": "COUPLE"},
{"name": "Limited Company", "value": "LIMITED_COMPANY"},
{"name": "Charity", "value": "CHARITY"},
{"name": "Pension", "value": "PENSION"},
{"name": "Trust", "value": "TRUST"},
{"name": "Council", "value": "COUNCIL"},
{"name": "Partnership", "value": "PARTNERSHIP"}
],
"conditions": null
},
{
"ref": "ftb_relief",
"question": "Are you eligible for First-Time Buyer Relief?",
"info": "\nWe're checking if you can claim a tax reduction for first-time buyers.\nTo answer 'Yes', both of the following must be true:\n- This is your (and anyone you are buying with's) very first property ownership, anywhere in the world.\n- You intend to live in this property as your main home.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "replacing_pr",
"question": "Will you be living in this property as your main home?",
"info": "\nA 'main home' is generally where you habitually live and where your family life is centred. \nIf you are selling a property that was your main home and buying a new one to replace it, you might avoid higher Stamp Duty rates that apply to additional properties. \nThis can still apply even if there's a short gap between selling and buying, provided you sell your old main home within 3 years of buying the new one.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "owns_other",
"question": "On the day you complete this purchase, will you (or any other buyer) own any other residential properties anywhere in the world?",
"info": "\nThis is to check if you need to pay the higher Stamp Duty rates for additional properties. Please answer 'Yes' if you own an interest in another property that:\n- Is located anywhere in the world.\n- You own in whole or in part (even a tiny share).\n- You acquired by any means - whether you purchased it, were gifted it, or inherited it.\n- Is owned on a long lease with more than 21 years remaining.\n- You are a beneficiary of a trust that owns a residential property. (Note: if the beneficiary is under 18, the property may be treated as belonging to their parents for tax purposes).\nThe only property you should ignore when answering this question is the main home you are in the process of selling.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "uk_resident",
"question": "On the day of purchase, will all buyers have been physically present in the UK for at least 183 days during the previous 12 months?",
"info": "\nThis question helps us determine if a special 2% Stamp Duty surcharge for non-UK residents applies to your purchase. \nA buyer is generally considered a UK resident if they've been in the UK for more than 183 days (about half the year) in the 365 days prior to midnight on the day of completion.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "current_use",
"question": "What is the current main use of the property?",
"info": "\nThe main use of a property determines which set of Stamp Duty rates applies. \n- Residential: A home, flat, or building suitable for living, including its garden and grounds. Properties being built as homes also fall here. \n- Mixed: A property that has both a residential part (like your home) and a distinct non-residential part (like a shop below, or land used for business). This can sometimes result in different Stamp Duty rates. \n- Commercial: Properties such as shops, offices, factories, or barns that are not used as homes. \n- Development: Any land or building with official permission (granted or pre-approved) to be converted into homes.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Residential", "value": "RESIDENTIAL"},
{"name": "Mixed", "value": "MIXED"},
{"name": "Commercial", "value": "COMMERCIAL"},
{"name": "Development", "value": "DEVELOPMENT"}
],
"conditions": null
},
{
"ref": "intended_use",
"question": "What is the intended main use of the property?",
"info": "\nThis helps us confirm if the future use of the property aligns with its current use, or if there are plans to change it. \nYour answer here helps us apply the correct Stamp Duty rules. \n- Residential: A home, flat, or building suitable for living, including its garden and grounds. Properties being built as homes also fall here. \n- Mixed: A property that has both a residential part (like your home) and a distinct non-residential part (like a shop below, or land used for business). This can sometimes result in different Stamp Duty rates. \n- Commercial: Properties such as shops, offices, factories, or barns that are not used as homes. \n- Development: Any land or building with official permission (granted or pre-approved) to be converted into homes.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Residential", "value": "RESIDENTIAL"},
{"name": "Mixed", "value": "MIXED"},
{"name": "Commercial", "value": "COMMERCIAL"},
{"name": "Development", "value": "DEVELOPMENT"}
],
"conditions": null
},
{
"ref": "is_dwelling",
"question": "Is the property currently suitable for use as a home (dwelling)?",
"info": "\nA property is generally 'suitable' if someone could live in it today. \nAnswer 'NO' if it is derelict or a 'shell' lacking basic facilities like a functioning kitchen or bathroom.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "being_converted",
"question": "Is the property currently being built or converted to be suitable as a home (dwelling)?",
"info": "\nThis applies if the property isn't a home yet, but construction or adaptation work is actively underway to make it one. \nSimply having planning permission isn't enough; physical work must have started.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": {"is_dwelling": "NO"}
},
{
"ref": "is_development",
"question": "Does the property have planning permission to be converted into homes, but building work has not yet started?",
"info": "\nThis applies if the property isn't a home yet, and isn't currently being built as one, \nbut it has official planning permission (granted or pre-approved) to be converted into homes.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": {"being_converted": "NO"}
},
{
"ref": "is_purchase",
"question": "Does the purchase include any buildings?",
"info": "Answer 'NO' only if you are buying a plot of land with absolutely no buildings on it at all (e.g., a field, woodland, or an empty building plot).",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "has_annexes",
"question": "Does the property include any additional self-contained living spaces (like an annexe or separate flat)?",
"info": "\nThe number of separate living spaces (dwellings) within a property can impact Stamp Duty. \nAn annexe or separate flat counts if it has its own kitchen, bathroom, and can be used independently from the main house. Note that the old 'Multiple Dwellings Relief' (MDR) was abolished on 1st June 2024.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
},
{
"ref": "num_dwellings",
"question": "How many separate homes are you buying in this transaction?",
"info": "\nThe total number of homes (or 'dwellings') can affect the tax calculation, especially if you buy six or more at once.\nWhat to count: Include the main house, plus any fully self-contained annexes or separate flats that are part of the purchase. A space is 'self-contained' if it has its own kitchen, bathroom, and entrance.\n- Important: If you're buying one flat in a block of 50, please enter 1.\n- If you are only buying land with no buildings, please enter 0.\n ",
"responseType": "number",
"responseOptions": null,
"conditions": null
},
{
"ref": "has_grounds",
"question": "Is any part of the land or buildings used for business purposes?",
"info": "\nIf a property has both a home and a separate business element, it might be classed as 'mixed-use', which changes the tax rules.\n- Please answer 'Yes' if the property includes things like a working farm, an office you rent to someone else, or commercial woodland.\n- You can answer 'No' for things like a home office for your own use, a personal garden, or a paddock used privately for your own horse.\n ",
"responseType": "radio_button",
"responseOptions": [
{"name": "Yes", "value": "YES"},
{"name": "No", "value": "NO"}
],
"conditions": null
}
]
}