Clients

A "client" represents an individual client, or a couple, that your firm serves. The client is the top-level record that everything else you send over SFTP belongs to: people, trusts, entities, and assets all belong to a client, and entitlements grant users access to clients.

The SFTP interface adds and updates clients in bulk; it never deletes them. A client that stops appearing in the file is left unchanged, not removed — so you can send either your full client list or only the clients that changed. Adding or updating clients is performed by uploading a JSONL (JSON Lines) file, where each line represents a client object.

To remove a client, use the Delete Client API, addressing it by the same id you send here (its external_id). Note that this revokes the advisor's access to the client rather than removing the client from the Wealth.com platform.

A client in this file corresponds to the client resource of the Advisor API; the Clients file is the bulk, full-load SFTP equivalent of the Add Client endpoint.

The client's id is what the rest of your files reference. Supply it as client_id in the Entitlement, People/Trusts/Entities, and Asset files.

SFTP

Clients File Specification

JSONL File Schema

  • Name
    id
    Type
    string (Max 255)
    Description

    Your firm's unique identifier for the client. This is the client_id referenced by the Entitlement, People/Trusts/Entities, and Asset files.

  • Name
    primary_id
    Type
    string (Max 255), optional
    Description

    The id from your People/Trusts/Entities file of the person who is this client's primary contact. Creating a client automatically creates a primary contact record for that person; providing primary_id links it to the matching People file row so that row updates the primary contact in place instead of creating a duplicate. Recommended whenever the primary contact also appears in the People file. If omitted, the primary contact is still created but is not linked to a People file row.

  • Name
    email
    Type
    string (Max 255), optional
    Description

    Email of the client. When provided, it is the address the client's invitation is sent to so they can create their login. May be omitted if you do not have an email for the client yet; the client can be invited later once an email is available.

  • Name
    first_name
    Type
    string (Max 255)
    Description

    First name of the client.

  • Name
    last_name
    Type
    string (Max 255)
    Description

    Last name of the client.

  • Name
    send_invitation_email
    Type
    boolean, optional
    Description

    Whether Wealth.com should send an invitation email to the client. Defaults to false; the default is to not send an invitation email and to let your system invite the client. Only takes effect the first time a client is invited, and only when an email is present. Inviting a client is how they can create a login and become a Wealth.com user — clients are not listed in the Users file.

  • Name
    subscription_start_date
    Type
    ISO 8601 date-time, optional
    Description

    The client's subscription start date. Must be in the past. If not provided, or set in the future, the current date is used.

  • Name
    marital_status
    Type
    enum (Single | Married | DomesticPartnership | CivilUnion | Engaged | OtherCommittedRelationship | Widowed), optional
    Description

    The client's marital status.

  • Name
    spouse_first_name
    Type
    string (Max 255), optional
    Description

    First name of the client's spouse.

  • Name
    spouse_last_name
    Type
    string (Max 255), optional
    Description

    Last name of the client's spouse.

  • Name
    spouse_id
    Type
    string (Max 255), optional
    Description

    The id from your People/Trusts/Entities file of the person who is this client's spouse. Behaves like primary_id for the spouse contact: it links the automatically created spouse contact record to the matching People file row so that row updates it in place instead of creating a duplicate. Only meaningful when the client has a spouse.

  • Name
    address
    Type
    object, optional
    Description

    The client's address.

    • line1: string (Max 255), optional - Street address line 1.
    • line2: string (Max 255), optional - Street address line 2.
    • city: string (Max 255), optional - City.
    • state: string (Max 255), optional - State.
    • zip: string (Max 255), optional - Zip code.
  • Name
    has_children
    Type
    boolean, optional
    Description

    Whether the client has children.

  • Name
    has_pets
    Type
    boolean, optional
    Description

    Whether the client has pets.

  • Name
    own_property
    Type
    boolean, optional
    Description

    Whether the client owns the property at the provided address.

  • Name
    existing_estate_plan
    Type
    enum (IndividualTrust | JointTrust | LastWillAndTestament | NoEstatePlan | Unknown), optional
    Description

    The client's existing estate plan.

  • Name
    selected_primary_document
    Type
    enum, optional
    Description

    The primary document the client selected. Accepted values:

    'One Joint Revocable Trust'
'One Individual Revocable Trust'
'Two Individual Revocable Trusts'
'One Last Will and Testament'
'Two Last Will and Testaments'

Example JSONL File

clients.jsonl

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "primary_id": "ca7e299a-5404-4d10-82f4-584ebb1bee54",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "send_invitation_email": false,
  "subscription_start_date": "2024-02-01T00:00:00Z",
  "marital_status": "Married",
  "spouse_first_name": "Jane",
  "spouse_last_name": "Doe",
  "spouse_id": "4c59a99e-49e9-4364-afa6-22d62d9af3a7",
  "address": {
    "line1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "90210"
  },
  "has_children": true,
  "has_pets": false,
  "own_property": true,
  "existing_estate_plan": "JointTrust",
  "selected_primary_document": "One Joint Revocable Trust"
}
{
  "id": "987e6543-e21b-45c6-b789-123456789abc",
  "primary_id": "1694a501-5aad-48d0-8888-75801e16b1e2",
  "email": "john.smith@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "marital_status": "Single",
  "selected_primary_document": "One Individual Revocable Trust"
}