Calculations

Calculations are the core model of Stamp Expert. They are used to calculate the Stamp Duty Land Tax (SDLT) for a given property transaction.

The calculation request

The calculation model contains all the information required to provide a calculation estimate. It will contain the calculated Stamp Duty Land Tax (SDLT) amount in the case of a "standard" calculation, or the lowest and highest possible SDLT amounts in the case of a "non-standard" calculation.

Properties

Name
case_ref
Type
string
Description
Case Reference - a unique identifier for the property being calculated. Always required
Name
country
Type
enum
Description
Purchase Country. Must be one of: "ENGLAND", "WALES", "SCOTLAND". Always required
Name
is_leasehold
Type
enum
Description
Whether the property is subject to a lease. Must be either "YES" or "NO". Always required
Name
lease_nature
Type
enum
Description
The nature of the lease transaction. Must be one of: "NEW", "EXTENSION", "TAKEOVER". Required only when is_leasehold is "YES"
Name
lease_type
Type
enum
Description
The type of lease payment. Must be either "RENT" or "PREMIUM". Required only when is_leasehold is "YES"
Name
lease_other_property
Type
enum
Description
Whether this lease is part of a larger deal involving other property transactions. Must be either "YES" or "NO". Required only when is_leasehold is "YES"
Name
lease_commercial
Type
enum
Description
For commercial leases: whether the tenant is a company claiming specific SDLT relief. Must be either "YES" or "NO". Required only when is_leasehold is "YES"
Name
lease_prior_possession
Type
enum
Description
Whether possession was taken or rent paid before the formal lease grant date. Must be either "YES" or "NO". Required only when is_leasehold is "YES"
Name
lease_premium
Type
integer
Description
The total premium payable for the lease in pounds. Must be a positive integer. Required only when is_leasehold is "YES" and lease_type is "PREMIUM"
Name
lease_premium_vat
Type
enum
Description
Whether VAT is payable on the lease premium. Must be either "YES" or "NO". Required only when is_leasehold is "YES" and lease_type is "PREMIUM"
Name
lease_term
Type
integer
Description
The term of the lease in years. Must be between 0 and 125. Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
lease_rent_year_1
Type
integer
Description
The rent payable for the first year in pounds. Must be a positive integer. Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
lease_rent_year_2
Type
integer
Description
The rent payable for the second year in pounds. Must be a positive integer. Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
lease_rent_year_3
Type
integer
Description
The rent payable for the third year in pounds. Must be a positive integer. Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
lease_rent_year_4
Type
integer
Description
The rent payable for the fourth year in pounds. Must be a positive integer. Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
lease_rent_year_5
Type
integer
Description
The rent payable for the fifth year in pounds. Must be a positive integer. Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
lease_term_vat
Type
enum
Description
Whether VAT is payable on the rent. Must be either "YES" or "NO". Required only when is_leasehold is "YES" and lease_type is "RENT"
Name
property_value
Type
integer
Description
The value of the property in pounds. Must be a positive integer. Required only when is_leasehold is "NO"
Name
buyer_type
Type
enum
Description
Who is buying the property. Must be one of: "INDIVIDUAL", "COUPLE", "LIMITED_COMPANY", "CHARITY", "PENSION", "TRUST", "COUNCIL", "PARTNERSHIP". Always required
Name
ftb_relief
Type
enum
Description
Whether all purchasers are eligible for First Time Buyers relief. Must be either "YES" or "NO". Always required
Name
replacing_pr
Type
enum
Description
Whether all purchasers are replacing their Primary residence. Must be either "YES" or "NO". Always required
Name
owns_other
Type
enum
Description
Whether any of the purchasers own a benefit in any other property. Must be either "YES" or "NO". Always required
Name
uk_resident
Type
enum
Description
Whether ALL purchasers have been resident in UK for longer than 183 days in the 365 days prior to completion. Must be either "YES" or "NO". Always required
Name
current_use
Type
enum
Description
Current use of the property. Must be one of: "RESIDENTIAL", "MIXED", "COMMERCIAL", "DEVELOPMENT". Always required
Name
intended_use
Type
enum
Description
Intended use of the property. Must be one of: "RESIDENTIAL", "MIXED", "COMMERCIAL", "DEVELOPMENT". Always required
Name
is_dwelling
Type
enum
Description
Whether the property is currently suitable for use as a dwelling. Must be either "YES" or "NO". Always required
Name
being_converted
Type
enum
Description
Whether the dwelling(s) are in the process of being converted/constructed to be suitable. Must be either "YES" or "NO". Required only when is_dwelling is "NO".
Name
is_development
Type
enum
Description
Whether this is a development. Must be either "YES" or "NO". Required only when being_converted is "NO".
Name
is_purchase
Type
enum
Description
Whether this is a purchase of a property. Must be either "YES" or "NO". Always required
Name
has_annexes
Type
enum
Description
Whether the property has annexes or additional cottages, flats or independent accommodation. Must be either "YES" or "NO". Always required
Name
has_grounds
Type
enum
Description
Whether the property has grounds/paddocks/stables/farm buildings or barns with current or former business or commercial use. Must be either "YES" or "NO". Always required
Name
num_dwellings
Type
integer
Description
Number of separate dwellings including any main house, annexes or additional cottages. Must be a positive integer. Always required
Name
is_leasehold
Type
enum
Description
Whether the property is subject to a lease. Must be either "YES" or "NO". Always required
Name
completion_date
Type
datetime
Description
The date of completion for the property transaction. Format: YYYY-MM-DDTHH:MM:SS. Always required
Name
is_refinance
Type
enum
Description
Whether this is a remortgage or Transfer of Equity. Must be either "YES" or "NO". Optional field
Name
party_change
Type
enum
Description
Whether the number of parties is changing. Must be one of: "NOT_CHANGING", "TWO_TO_ONE", "ONE_TO_MORE". Required only when is_refinance is "YES"
Name
is_married
Type
enum
Description
Whether the parties are married. Must be either "YES" or "NO". Required only when is_refinance is "YES"
Name
is_divorcing
Type
enum
Description
Whether they are currently divorcing or divorced. Must be either "YES" or "NO". Required only when is_refinance is "YES"
Name
money_changing
Type
enum
Description
Whether money is changing hands apart from the mortgage. Must be either "YES" or "NO". Required only when is_refinance is "YES"
Name
lump_sum
Type
enum
Description
Whether a lump sum is to be paid to one of the existing parties by another. Must be either "YES" or "NO". Required only when is_refinance is "YES"
Name
full_ownership
Type
enum
Description
Whether all parties on the original mortgage owned the property in its entirety. Must be either "YES" or "NO". Required only when is_refinance is "YES"
Name
new_mortgage_val
Type
integer
Description
The total value of the new mortgage. Must be a positive integer. Required only when is_refinance is "YES"
Name
share_change
Type
enum
Description
Whether the percentages they own are changing. Must be either "YES" or "NO". Required only when is_refinance is "YES"
Name
share_before
Type
float
Description
How much of a share (as percent) they owned before. Must be between 0 and 100. Required only when share_change is "YES"
Name
share_after
Type
float
Description
How much of a share (as percent) they will own after. Must be between 0 and 100. Required only when share_change is "YES"
Name
customer_email
Type
string
Description
The email of the client requesting the stamp calculation. Always required
Name
customer_phone
Type
string
Description
The phone number of the client requesting the stamp calculation. Optional field
Name
customer_first_name
Type
string
Description
The first name of the client requesting the stamp calculation. Always required
Name
customer_last_name
Type
string
Description
The last name of the client requesting the stamp calculation. Always required
Name
sender_email
Type
string
Description
The email of the person or organization making the request on behalf of the client. Always required
Name
sender_organization_name
Type
string
Description
The name of the organization making the request. Always required
Name
sender_first_name
Type
string
Description
The first name of the person making the request. Always required
Name
sender_last_name
Type
string
Description
The last name of the person making the request. Always required

The calculation response

The response will contain the calculated Stamp Duty Land Tax (SDLT) amount in the case of a "standard" calculation, or the lowest and highest possible SDLT amounts in the case of a "non-standard" calculation.

Properties

Name
uuid
Type
string
Description
The unique ID of the calculation. This is a ShortUUID format identifier for the calculation record.
Name
created_at
Type
datetime
Description
The date and time when the calculation was created. Format: YYYY-MM-DDTHH:MM:SS.
Name
updated_at
Type
datetime
Description
The date and time when the calculation was last updated. Format: YYYY-MM-DDTHH:MM:SS.
Name
response_type
Type
string
Description
Whether the calculation is standard or non-standard. Values: "STANDARD" or "NON_STANDARD". Standard calculations have the same low and high values, while non-standard calculations may have different ranges.
Name
low_value
Type
integer
Description
The lowest estimated value of the SDLT (Stamp Duty Land Tax) in pounds. This represents the minimum tax amount calculated.
Name
high_value
Type
integer
Description
The highest estimated value of the SDLT (Stamp Duty Land Tax) in pounds. This represents the maximum tax amount calculated. For standard calculations, this will be the same as low_value.
Name
status
Type
enum
Description
The status of the calculation. Values: "CALCULATED", "PAID", "ACCEPTED", "DECLINED", or "ADVICE_ISSUED". CALCULATED means the calculation has been completed, PAID means payment has been received, ACCEPTED means the calculation has been accepted, DECLINED means the calculation has been declined, and ADVICE_ISSUED means advice has been issued.
Name
decline_message
Type
string
Description
A message explaining why the calculation was declined, if the status is "DECLINED". This will be null for all other statuses.
Name
customer_email
Type
string
Description
The email of the client requesting the stamp calculation. This is copied from the request data for reference.
Name
customer_phone
Type
string
Description
The phone number of the client requesting the stamp calculation. This is copied from the request data for reference.
Name
customer_first_name
Type
string
Description
The first name of the client requesting the stamp calculation. This is copied from the request data for reference.
Name
customer_last_name
Type
string
Description
The last name of the client requesting the stamp calculation. This is copied from the request data for reference.
Name
sender_email
Type
string
Description
The email of the person or organization making the request on behalf of the client. This is copied from the request data for reference.
Name
sender_organization_name
Type
string
Description
The name of the organization making the request. This is copied from the request data for reference.
Name
sender_first_name
Type
string
Description
The first name of the person making the request. This is copied from the request data for reference.
Name
sender_last_name
Type
string
Description
The last name of the person making the request. This is copied from the request data for reference.
Name
document_id
Type
string
Description
The document ID of the PDF from the PDF service. This is the unique identifier for the PDF document.
Name
document_url
Type
string
Description
The public URL of the PDF document. This is the preferred way to access the PDF document.
Name
request_id
Type
string
Description
The unique ID of the request associated with this calculation, if any. This will be null if the calculation was created directly without a request.
Name
customer_id
Type
string
Description
The unique ID of the customer associated with this calculation, if any. This will be null if no customer record exists.
Name
selected_tax_advisor_uuid
Type
string
Description
The unique ID of the selected tax advisor, if one has been selected. This will be null if no tax advisor has been selected yet.
Name
selected_tax_advisor
Type
object
Description
The full tax advisor data if a tax advisor has been selected. This will be null if no tax advisor has been selected yet. Contains the same fields as objects in the tax_advisors array.
Name
tax_advisors
Type
array
Description
List of tax advisor firms and their calculated legal fees. Each tax advisor object contains uuid, name, bio, logo_url, legal_fee, and engagement_terms_url fields. This provides recommendations for legal representation.
Name
questionnaire
Type
object
Description
The complete questionnaire data used for the calculation. This contains only the questionnaire-related fields (case_ref, country, property_value, buyer_type, etc.) and does not include customer or sender information, which are provided as separate top-level fields.
Name
matching_condition_sets
Type
array
Description
The matching condition sets for the calculation. This is the condition sets that were matching the tax tables.
Name
calculation_url
Type
string
Description
The URL of the calculation. This is a direct link to the calculation, which can be used to view the calculation in the Stamp Expert app. This will be null if the calculation was created via the external API (not the calculator API).

Tax advisors properties

Name
uuid
Type
string
Description
The unique ID of the tax advisor firm. This is a ShortUUID format identifier for the tax advisor firm record.
Name
name
Type
string
Description
The name of the tax advisor firm. This is the official business name of the tax advisory company that can provide legal services for the SDLT transaction.
Name
bio
Type
string
Description
Information about the tax advising firm. This may include details about the firm's expertise, services offered, or any additional information that helps clients understand what the firm provides. Optional field.
Name
engagement_terms_url
Type
string
Description
The URL of the engagement terms document for the tax advisor. This provides a direct link to the terms and conditions that apply when engaging this tax advisor. Optional field.
Name
logo_url
Type
string
Description
The logo URL of the tax advisor website. This provides a direct link to the firm's logo image, typically used for display purposes in user interfaces. Optional field.
Name
legal_fee
Type
integer
Description
The value of the legal fee for the calculated SDLT transaction in pounds. This represents the estimated cost for the tax advisor's services based on the specific property transaction details and is calculated using the firm's fee structure.

Matching condition sets properties

Name
table_id
Type
string
Description
The unique ID of the rate table that was used for the calculation. This is a ShortUUID format identifier for the rate table record.
Name
table_title
Type
string
Description
The title of the rate table that was used for the calculation. This provides a human-readable name for the rate table.
Name
table_rate_type
Type
enum
Description
The type of rate table that was used. This indicates the category of SDLT rate that was applied (e.g., "STANDARD_RESIDENTIAL", "FIRST_TIME_BUYERS_RELIEF", "ADDITIONAL_RATE", etc.).
Name
condition_set_title
Type
string
Description
The title of the condition set that matched the questionnaire data. This provides a human-readable name for the specific conditions that were satisfied.
Name
condition_set_description
Type
string
Description
A detailed description of the condition set that matched. This explains the specific criteria that were met to apply this rate table to the calculation.

The matching condition sets provide transparency into how the SDLT calculation was determined. Each condition set represents a specific combination of questionnaire answers that qualified the transaction for a particular rate table. This helps users understand which tax rules and conditions were applied to their specific property transaction.

POST/v1/calculate

Create a calculation

This endpoint allows you to create a new calculation. To create a calculation, you must authenticate with the Stamp Expert API using an OAuth2 token and provide the calculation details.

Required attributes

Please refer to the calculation request for the required and optional attributes.

Optional attributes

Some attributes are only required for certain scenarios. Please refer to the calculation request for the required and optional attributes.

Request

POST

/v1/calculate

curl --request POST \
  --url https://api.stamp.expert/v1/calculate \
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --header 'User-Agent: insomnia/11.3.0' \
  --data '{
  "case_ref": "PROP123",
  "is_refinance": "NO",
  "country": "ENGLAND",
  "property_value": 500000,
  "buyer_type": "INDIVIDUAL",
  "ftb_relief": "NO",
  "replacing_pr": "YES",
  "owns_other": "NO",
  "uk_resident": "YES",
  "current_use": "RESIDENTIAL",
  "intended_use": "RESIDENTIAL",
  "is_dwelling": "YES",
  "is_purchase": "YES",
  "has_annexes": "NO",
  "has_grounds": "NO",
  "num_dwellings": 1,
  "is_leasehold": "NO",
  "completion_date": "2025-04-01T00:00:00",
  "customer_email": "john.doe@example.com",
  "customer_phone": "+447123456789",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "sender_email": "lawyer@lawfirm.com",
  "sender_organization_name": "Test Law Firm",
  "sender_first_name": "Jane",
  "sender_last_name": "Smith"
}'

Response

{
  "uuid": "cal_V5577AWkcZ",
  "created_at": "2025-07-16T06:35:51Z",
  "updated_at": "2025-07-16T06:35:51Z",
  "response_type": "STANDARD",
  "low_value": 15000,
  "high_value": 15000,
  "status": "CALCULATED",
  "customer_email": "john.doe@example.com",
  "customer_phone": "+447123456789",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "sender_email": "lawyer@lawfirm.com",
  "sender_organization_name": "Test Law Firm",
  "sender_first_name": "Jane",
  "sender_last_name": "Smith",
  "document_id": "doc_1234567890",
  "document_url": "https://micro-pdf-production.s3.amazonaws.com/stamp-expert/Stamp-Expert-cal_Uvuqe9ZFNW.pdf",
  "request_id": null,
  "customer_id": null,
  "selected_tax_advisor_uuid": null,
  "selected_tax_advisor": null,
  "tax_advisors": [
    {
      "uuid": "tax_nqRvHg2U3N",
      "name": "Marks & Sons Tax Advisors",
      "bio": null,
      "logo_url": null,
      "legal_fee": 300,
      "engagement_terms_url": null
    },
    {
      "uuid": "tax_nqRvHg2U3L",
      "name": "Tax 4 U",
      "bio": null,
      "logo_url": null,
      "legal_fee": 300,
      "engagement_terms_url": null
    }
  ],
  "questionnaire": {
    "case_ref": "PROP123",
    "is_refinance": "NO",
    "country": "ENGLAND",
    "property_value": 500000,
    "buyer_type": "INDIVIDUAL",
    "ftb_relief": "NO",
    "replacing_pr": "YES",
    "owns_other": "NO",
    "uk_resident": "YES",
    "current_use": "RESIDENTIAL",
    "intended_use": "RESIDENTIAL",
    "is_dwelling": "YES",
    "being_converted": null,
    "is_development": null,
    "is_purchase": "YES",
    "has_annexes": "NO",
    "has_grounds": "NO",
    "num_dwellings": 1,
    "is_leasehold": "NO",
    "completion_date": "2025-04-01T00:00:00",
    "party_change": null,
    "is_married": null,
    "is_divorcing": null,
    "money_changing": null,
    "lump_sum": null,
    "full_ownership": null,
    "new_mortgage_val": null,
    "share_change": null,
    "share_before": null,
    "share_after": null,
    "account_id": null
  },
  "matching_condition_sets": [
    {
      "table_id": "rtb_ABC123",
      "table_title": "Standard Residential Rates 2024",
      "table_rate_type": "STANDARD_RESIDENTIAL",
      "condition_set_title": "Standard Purchase",
      "condition_set_description": "Standard residential property purchase with no special reliefs or conditions"
    }
  ],
  "calculation_url": "https://app.stamp.expert/calculator/calculation/cal_T2wqB84UPq?secret=EEhTGRAzcCPHpbIYxdek4LQE0dvike99EOmBy4IaLg0"
}

GET/v1/calculate/:uuid

Retrieve a calculation

This endpoint allows you to retrieve a calculation by providing its unique identifier. Refer to the list at the top of this page to see which properties are included with calculation objects.

Request

GET

/v1/calculate/cal_c6noZZkYGB

curl https://api.stamp.expert/v1/calculate/cal_c6noZZkYGB \
  -H "Authorization: Bearer {token}"

Response

{
  "uuid": "cal_c6noZZkYGB",
  "created_at": "2025-07-16T07:08:52",
  "updated_at": "2025-07-16T07:08:52",
  "response_type": "STANDARD",
  "low_value": 15000,
  "high_value": 15000,
  "status": "CALCULATED",
  "customer_email": "john.doe@example.com",
  "customer_phone": "+447123456789",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "sender_email": "lawyer@lawfirm.com",
  "sender_organization_name": "Test Law Firm",
  "sender_first_name": "Jane",
  "sender_last_name": "Smith",
  "document_id": "doc_1234567890",
  "document_url": "https://micro-pdf-production.s3.amazonaws.com/stamp-expert/Stamp-Expert-cal_Uvuqe9ZFNW.pdf",
  "request_id": null,
  "customer_id": null,
  "selected_tax_advisor_uuid": null,
  "selected_tax_advisor": null,
  "tax_advisors": [
    {
      "uuid": "tax_nqRvHg2U3N",
      "name": "Marks & Sons Tax Advisors",
      "bio": null,
      "logo_url": null,
      "legal_fee": 300,
      "engagement_terms_url": null
    },
    {
      "uuid": "tax_nqRvHg2U3L",
      "name": "Tax 4 U",
      "bio": null,
      "logo_url": null,
      "legal_fee": 300,
      "engagement_terms_url": null
    }
  ],
  "questionnaire": {
    "case_ref": "PROP123",
    "is_refinance": "NO",
    "country": "ENGLAND",
    "property_value": 500000,
    "buyer_type": "INDIVIDUAL",
    "ftb_relief": "NO",
    "replacing_pr": "YES",
    "owns_other": "NO",
    "uk_resident": "YES",
    "current_use": "RESIDENTIAL",
    "intended_use": "RESIDENTIAL",
    "is_dwelling": "YES",
    "being_converted": null,
    "is_development": null,
    "is_purchase": "YES",
    "has_annexes": "NO",
    "has_grounds": "NO",
    "num_dwellings": 1,
    "is_leasehold": "NO",
    "completion_date": "2025-04-01T00:00:00",
    "party_change": null,
    "is_married": null,
    "is_divorcing": null,
    "money_changing": null,
    "lump_sum": null,
    "full_ownership": null,
    "new_mortgage_val": null,
    "share_change": null,
    "share_before": null,
    "share_after": null,
    "account_id": null
  },
  "matching_condition_sets": [
    {
      "table_id": "rtb_ABC123",
      "table_title": "Standard Residential Rates 2024",
      "table_rate_type": "STANDARD_RESIDENTIAL",
      "condition_set_title": "Standard Purchase",
      "condition_set_description": "Standard residential property purchase with no special reliefs or conditions"
    }
  ],
  "calculation_url": "https://app.stamp.expert/calculator/calculation/cal_T2wqB84UPq?secret=EEhTGRAzcCPHpbIYxdek4LQE0dvike99EOmBy4IaLg0"
}