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.
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)
| Field | Type | Description |
|---|---|---|
will_ | date | Date of the existing will (YYYY-MM-DD) |
original_ | string | Where the original will is kept |
next_ | date | When the will should next be reviewed (YYYY-MM-DD) |
existing_ | string | Your reference for the existing will |
notes | string | Free-text notes |
Testator (the person making the will)
| Field | Type | Description |
|---|---|---|
title | string | Title/salutation (Mr, Mrs, Ms, Miss, Dr, Prof, Sir, Dame, Lord, Lady) |
first_ | string | First/given name |
middle_ | string | Middle name(s) |
last_ | string | Last/family name |
name | string | Full name (used if first/last not provided; title and middle name are parsed automatically) |
date_ | date | Date of birth (YYYY-MM-DD) |
address | string | Full residential address |
email | Email address | |
phone | string | Phone number with country code |
marital_ | string | single, married, divorced, widowed, separated, or civil_partnership |
nationality | string or array | Citizenship(s): a single string or an array of strings |
occupation | string | Current occupation or profession |
primary_ | string | Primary language (e.g. English, French) |
has_ | boolean | Whether the testator has been known by other names |
other_ | array of strings | Other names the testator has been known by (maiden name, etc.) |
Jurisdiction
| Field | Type | Description |
|---|---|---|
country | string | Country name or ISO 3166-1 alpha-2 code (e.g. GB, US) |
state | string | State, region, or province (e.g. England, California) |
Children (array)
| Field | Type | Description |
|---|---|---|
name | string | Child’s full name (required) |
date_ | date | Date of birth (YYYY-MM-DD) |
is_ | boolean | True if child is under 18 |
special_ | string | Free-text description of any special needs (medical, developmental, behavioural). Leave empty if none. |
Pets (array)
| Field | Type | Description |
|---|---|---|
name | string | Pet’s name (required) |
species | string | Type of animal (e.g. dog, cat, bird) |
breed | string | Breed 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.
| Field | Type | Description |
|---|---|---|
name | string | Executor’s name (required) |
relationship | string | Relationship to the testator (e.g. spouse, solicitor) |
is_ | boolean | True if this is a professional executor (solicitor, bank, etc.) |
is_ | boolean | True if this is a reserve/backup executor |
address | string | Address |
email | Email address | |
phone | string | Phone number |
Beneficiaries (array)
| Field | Type | Description |
|---|---|---|
name | string | Beneficiary’s name (required) |
relationship | string | Relationship to the testator |
date_ | date | Date of birth (YYYY-MM-DD) |
is_ | boolean | True if beneficiary is under 18 |
Guardians (array)
Guardians appointed for minor children.
| Field | Type | Description |
|---|---|---|
name | string | Guardian’s name (required) |
relationship | string | Relationship to the testator |
kind | string | primary or backup (backup guardians serve only if the primary cannot) |
for_ | array of strings | Names of children this guardian is appointed for |
Assets (object)
High-level asset categories. Each field is an array of category strings.
| Field | Type | Description |
|---|---|---|
personal_ | array of strings | e.g. property, vehicles, bank_accounts, investments, pensions, insurance, personal_possessions, digital_assets |
business_ | array of strings | e.g. business_interests, intellectual_property, partnerships |
liabilities | array of strings | e.g. mortgage, loans, credit_cards |
Gifts (array)
Specific gifts, pecuniary legacies, and charitable donations.
| Field | Type | Description |
|---|---|---|
type | string | specific, pecuniary, or charitable |
description | string | Description of the gift or asset |
recipient | string | Name of the recipient |
amount | number | Monetary amount (for pecuniary gifts) |
currency | string | Currency code (e.g. GBP, USD) |
conditions | array of strings | Conditions attached to the gift |
Residuary estate (object)
How the remainder of the estate is distributed after specific gifts.
| Field | Type | Description |
|---|---|---|
distribution[]. | string | Name of the recipient |
distribution[]. | string | Share of the residuary estate (e.g. 50%, equally) |
distribution_ | integer | Tier number. Tier 1 is the primary distribution; higher tiers apply if lower-tier beneficiaries predecease or cannot inherit |
distribution_ | string | Condition for this tier |
distribution_ | array of objects | Each with name, share, per_stirpes (boolean) and conditions (array of strings) |
Trusts (array)
| Field | Type | Description |
|---|---|---|
type | string | Type of trust (e.g. discretionary, life_interest) |
beneficiary | string | Trust beneficiary |
trustees | array of strings | Names of the trustees |
conditions | string | Trust conditions or terms |
Funeral wishes (object)
| Field | Type | Description |
|---|---|---|
burial_ | string | burial, cremation, other, or no_preference |
specific_ | string | Specific funeral wishes or instructions |
death_ | boolean | Whether to publish death notices |
online_ | boolean | Whether to make online announcements |
memorial_ | boolean | Whether to create a memorial website |
prepaid_ | boolean | Whether 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_namethroughbeneficiary_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.
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
trueorfalse(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
namefield (e.g. "Mr John William Smith") or as separatefirst_name,middle_name, andlast_namefields. If both are provided, the full name is used as given, so include only one form. - Reserve executors in JSON use
is_reserve: truewithin 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
