Structured import format guide

Complete reference for preparing your will data in JSON or CSV format. Only the testator’s name is required (a full name, or a first or last name). All other fields are optional.

Last reviewed

Overview

The structured import format allows you to bring will data into TheWILL.ai from another platform or system. Your data is parsed programmatically, with no AI processing involved.

The format supports 14 data sections covering everything from personal details and family members to assets, gifts, and funeral wishes. Each section fills the matching part of your will.

You can download the JSON schema or CSV template directly from the Import page under the Exported file option.

Data sections

Below is a complete reference of every section and field supported by the import format. Only the testator’s name is required: provide testator.name, or a first or last name. Include as many or as few of the other sections as you have available.

Will type

A single string at the root level. Accepted values: solo or mirror. Defaults to solo if not specified.

Will details (optional strings at the root level)

FieldTypeDescription
will_datedateDate of the existing will (YYYY-MM-DD)
original_will_locationstringWhere the original will is kept
next_review_datedateWhen the will should next be reviewed (YYYY-MM-DD)
existing_will_referencestringYour reference for the existing will
notesstringFree-text notes

Testator (the person making the will)

FieldTypeDescription
titlestringTitle/salutation (Mr, Mrs, Ms, Miss, Dr, Prof, Sir, Dame, Lord, Lady)
first_namestringFirst/given name
middle_namestringMiddle name(s)
last_namestringLast/family name
namestringFull name (used if first/last not provided; title and middle name are parsed automatically)
date_of_birthdateDate of birth (YYYY-MM-DD)
addressstringFull residential address
emailemailEmail address
phonestringPhone number with country code
marital_statusstringsingle, married, divorced, widowed, separated, or civil_partnership
nationalitystring or arrayCitizenship(s): a single string or an array of strings
occupationstringCurrent occupation or profession
primary_languagestringPrimary language (e.g. English, French)
has_other_namesbooleanWhether the testator has been known by other names
other_namesarray of stringsOther names the testator has been known by (maiden name, etc.)

Jurisdiction

FieldTypeDescription
countrystringCountry name or ISO 3166-1 alpha-2 code (e.g. GB, US)
statestringState, region, or province (e.g. England, California)

Children (array)

FieldTypeDescription
namestringChild’s full name (required)
date_of_birthdateDate of birth (YYYY-MM-DD)
is_minorbooleanTrue if child is under 18
special_needs_descriptionstringFree-text description of any special needs (medical, developmental, behavioural). Leave empty if none.

Pets (array)

FieldTypeDescription
namestringPet’s name (required)
speciesstringType of animal (e.g. dog, cat, bird)
breedstringBreed of the animal

Executors (array)

People or professionals appointed to carry out the will. Use the is_reserve flag to distinguish primary from reserve executors.

FieldTypeDescription
namestringExecutor’s name (required)
relationshipstringRelationship to the testator (e.g. spouse, solicitor)
is_professionalbooleanTrue if this is a professional executor (solicitor, bank, etc.)
is_reservebooleanTrue if this is a reserve/backup executor
addressstringAddress
emailemailEmail address
phonestringPhone number

Beneficiaries (array)

FieldTypeDescription
namestringBeneficiary’s name (required)
relationshipstringRelationship to the testator
date_of_birthdateDate of birth (YYYY-MM-DD)
is_minorbooleanTrue if beneficiary is under 18

Guardians (array)

Guardians appointed for minor children.

FieldTypeDescription
namestringGuardian’s name (required)
relationshipstringRelationship to the testator
kindstringprimary or backup (backup guardians serve only if the primary cannot)
for_childrenarray of stringsNames of children this guardian is appointed for

Assets (object)

High-level asset categories. Each field is an array of category strings.

FieldTypeDescription
personal_assetsarray of stringse.g. property, vehicles, bank_accounts, investments, pensions, insurance, personal_possessions, digital_assets
business_assetsarray of stringse.g. business_interests, intellectual_property, partnerships
liabilitiesarray of stringse.g. mortgage, loans, credit_cards

Gifts (array)

Specific gifts, pecuniary legacies, and charitable donations.

FieldTypeDescription
typestringspecific, pecuniary, or charitable
descriptionstringDescription of the gift or asset
recipientstringName of the recipient
amountnumberMonetary amount (for pecuniary gifts)
currencystringCurrency code (e.g. GBP, USD)
conditionsarray of stringsConditions attached to the gift

Residuary estate (object)

How the remainder of the estate is distributed after specific gifts.

FieldTypeDescription
distribution[].recipientstringName of the recipient
distribution[].sharestringShare of the residuary estate (e.g. 50%, equally)
distribution_tiers[].tierintegerTier number. Tier 1 is the primary distribution; higher tiers apply if lower-tier beneficiaries predecease or cannot inherit
distribution_tiers[].conditionstringCondition for this tier
distribution_tiers[].beneficiaries[]array of objectsEach with name, share, per_stirpes (boolean) and conditions (array of strings)

Trusts (array)

FieldTypeDescription
typestringType of trust (e.g. discretionary, life_interest)
beneficiarystringTrust beneficiary
trusteesarray of stringsNames of the trustees
conditionsstringTrust conditions or terms

Funeral wishes (object)

FieldTypeDescription
burial_cremationstringburial, cremation, other, or no_preference
specific_instructionsstringSpecific funeral wishes or instructions
death_noticesbooleanWhether to publish death notices
online_announcementsbooleanWhether to make online announcements
memorial_websitebooleanWhether to create a memorial website
prepaid_planbooleanWhether a prepaid funeral plan exists

Special provisions (array)

Additional clauses, conditions, or notes. Each item can be a simple string or an object with title and content fields.

JSON example

Below is a minimal JSON example showing the most common fields. Remember, only the testator’s name is required.

{
  "will_type": "solo",
  "testator": {
    "title": "Mr",
    "first_name": "John",
    "last_name": "Smith",
    "date_of_birth": "1970-01-15",
    "address": "123 High Street, London, EC2A 4NE",
    "marital_status": "married",
    "nationality": "British"
  },
  "jurisdiction": {
    "country": "GB",
    "state": "England"
  },
  "children": [
    {
      "name": "Thomas Smith",
      "date_of_birth": "2010-06-20",
      "is_minor": true
    }
  ],
  "executors": [
    {
      "name": "Jane Smith",
      "relationship": "spouse",
      "is_professional": false
    },
    {
      "name": "Robert Smith",
      "relationship": "brother",
      "is_reserve": true
    }
  ],
  "beneficiaries": [
    {
      "name": "Jane Smith",
      "relationship": "spouse"
    },
    {
      "name": "Thomas Smith",
      "relationship": "child"
    }
  ],
  "assets": {
    "personal_assets": ["property", "bank_accounts", "investments"],
    "business_assets": ["business_interests"]
  },
  "funeral_wishes": {
    "burial_cremation": "cremation"
  }
}

CSV format

The CSV format uses a flat column structure with numbered suffixes for arrays. Download the CSV template from the import page for the complete list of 61 columns with example data.

How arrays are represented:

  • Children use numbered columns: child_1_name, child_1_date_of_birth, child_2_name, etc.
  • Executors: executor_1_name, executor_2_name. Reserve executors use separate columns: reserve_executor_1_name.
  • Beneficiaries: beneficiary_1_name through beneficiary_3_name.
  • Asset categories are comma-separated within a single column: assets_personal = property,bank_accounts,investments.
  • Guardian children are semicolon-separated: guardian_1_for_children = Thomas Smith; Emily Smith.
The CSV template supports up to 2 children, 1 pet, 2 primary executors, 1 reserve executor, 3 beneficiaries, 1 guardian and 1 gift. For more entries, use the JSON format which has no limits on array sizes.

Format tips

  • Only the testator’s name is required. All other fields and sections are optional. Include as much or as little data as you have available.
  • Dates must be in ISO 8601 format: YYYY-MM-DD (e.g. 1970-01-15).
  • Booleans should be true or false (in CSV, use the strings "true" or "false").
  • Country codes can be ISO 3166-1 alpha-2 codes (GB, US, AU) or full country names.
  • JSON format is recommended for complex wills with many beneficiaries, gifts, or trust arrangements, as it has no limits on array sizes.
  • Testator name can be provided as a single name field (e.g. "Mr John William Smith") or as separate first_name, middle_name, and last_name fields. If both are provided, the full name is used as given, so include only one form.
  • Reserve executors in JSON use is_reserve: true within the executors array. In CSV, they have separate columns (reserve_executor_1_name).

Frequently asked questions

What happens to fields I don’t include?
Any sections or fields you leave out will simply be empty in your will. You can fill them in later while building your will.

Can I mix JSON and CSV formats?
No, each import must be a single file in one format. The format is auto-detected from the file extension (.json or .csv) or from the content when pasting directly.

What if my data has extra fields not listed here?
Extra fields are listed as unmapped on the field-mapping step and are skipped. Only fields matching the schema are imported.

Is there a size limit?
Yes. The import page shows the current size limit for structured data files.

Can’t find what you’re looking for?

Our support team is here to help. Contact us and we’ll get back to you as soon as possible.

Contact us

We use cookies to improve your experience. See our Cookie policy (opens in a new tab) for details.