Contact

This API is for the Contact resource of the Advisor API on the wealth.com platform. It allows connected systems to programmatically manage contact cards for a client. A contact card can represent an individual, trust, entity, charity, will, or class.

If your API user has access to multiple advisors, include advisor_id and team_id as query parameters on contact requests. These client-scoped paths also accept the client's external_id in place of wid — see Addressing a client.

Contact Types And Input Rules

The Contact resource supports the following values for type:

Individual
Trust
Entity
Charity
Will
Class

Common identifiers

Name
wid
Type
string
Description
Wealth.com top account identifier. Passed in the URL path for every contact endpoint.
Name
id
Type
string
Description
Wealth.com contact identifier. Returned by create, list, and get. Passed in the URL path for get and update.
Name
external_id
Type
string (Max 50)
Description
Your system's identifier for the contact. Required on create for every type. Immutable after creation.
Name
type
Type
enum
Description
Required on create. One of Individual, Trust, Entity, Charity, Will, or Class. Immutable after creation.

Individual

Individual is the person contact type. On create, external_id and type are required.

Name
first_name
Type
string (Max 200), optional
Description
First name for the individual contact.
Name
middle_name
Type
string (Max 200), optional
Description
Middle name for the individual contact.
Name
last_name
Type
string (Max 200), optional
Description
Last name for the individual contact.

Trust

On create, Trust requires legal_name. All other trust-specific fields are optional.

Name
legal_name
Type
string (Max 200)
Description
Required on create for trust contacts.
Name
trust_type
Type
string enum, optional
Description
Optional trust subtype. Valid values are listed below.
Name
trust_creator
Type
string array, optional
Description
Array of existing contact external_id values that should be recorded as trust creators.
Name
initial_trustee
Type
string array, optional
Description
Array of existing contact external_id values that should be recorded as initial trustees.
Name
governing_state
Type
string enum, optional
Description
Two-letter US state abbreviation such as FL or CA.
Name
trust_creation_date
Type
ISO 8601 date (`YYYY-MM-DD`), optional
Description
Trust creation date.

Valid `trust_type` values

IndividualRevocableTrust
JointRevocableTrust
IrrevocableLifeInsuranceTrust
GrantorRetainedAnnuityTrust
CharitableRemainderUnitTrust
CharitableRemainderAnnuityTrust
SpousalLifetimeAccessTrust
DynastyTrust
QualifiedPersonalResidenceTrust
OtherIrrevocableTrust

Entity

On create, Entity requires legal_name. Ownership and incorporation details are optional.

Name
legal_name
Type
string (Max 200)
Description
Required on create for entity contacts.
Name
incorporation_state
Type
string enum, optional
Description
Two-letter US state abbreviation such as FL or CA.
Name
incorporation_form
Type
string enum, optional
Description
Optional entity form. Valid values are listed below.
Name
ownership
Type
array, optional
Description
Ownership breakdown for the entity. Each entry is documented below.
Name
ownership[].percentage
Type
number
Description
Required when an ownership entry is supplied. Must be between 0 and 100.
Name
ownership[].owner_id
Type
string
Description
Use this field when a single contact owns the share. The value must be an existing contact external_id in the same top account.
Name
ownership[].subowners
Type
string array
Description
Use this field when multiple contacts jointly own the share. Each value must be an existing contact external_id in the same top account.

Valid `incorporation_form` values

CCorporation
SCorporation
DonorAdvisorFund
LimitedLiabilityCompany
LimitedPartnership
PrivateFoundation
SoleProprietorship
Other

Charity

On create, Charity requires legal_name, city, and state. All other charity-specific fields are optional.

Name
legal_name
Type
string (Max 200)
Description
Required on create for charity contacts.
Name
ein
Type
integer, optional
Description
Employer Identification Number for the charity.
Name
city
Type
string (Max 100)
Description
Required on create. City portion of the charity's address.
Name
state
Type
string enum
Description
Required on create. Two-letter US state abbreviation such as FL or CA.
Name
address_formatted
Type
string (Max 200), optional
Description
Formatted address line.
Name
notes
Type
string (Max 5000), optional
Description
Free-form notes for the charity.

Will

On create, Will requires both legal_name and will_type.

Name
legal_name
Type
string (Max 200)
Description
Required on create for will contacts.
Name
will_type
Type
string enum
Description
Required on create. Valid values are listed below.
Name
governing_state
Type
string enum, optional
Description
Two-letter US state abbreviation such as FL or CA.
Name
will_creation_date
Type
ISO 8601 date (`YYYY-MM-DD`), optional
Description
Will creation date.
Name
testator
Type
string array, optional
Description
Array of existing contact external_id values that should be recorded as testators.
Name
executor
Type
string array, optional
Description
Array of existing contact external_id values that should be recorded as executors.

Valid `will_type` values

LastWillAndTestament
PourOverWill

Class

On create, Class requires legal_name. The class can also include notes and a current_parties designation.

Name
legal_name
Type
string (Max 200)
Description
Required on create for class contacts.
Name
notes
Type
string (Max 5000), optional
Description
Free-form notes for the class contact.
Name
current_parties
Type
object, optional
Description
Current parties designation for the class.
Name
current_parties.is_distributed_evenly
Type
boolean, optional
Description
Indicates whether the class is distributed evenly.
Name
current_parties.share_amount
Type
string (Max 50), optional
Description
Optional share amount label or display value.
Name
current_parties.parties
Type
array
Description
Required when current_parties is supplied.
Name
current_parties.parties[].contact_id
Type
string
Description
Required for each party. Must be an existing contact external_id in the same top account.
Name
current_parties.parties[].distribution_percentage
Type
number, optional
Description
Optional percentage for the party. Must be between 0 and 100.
Name
current_parties.parties[].fraction
Type
object, optional
Description
Optional fraction for the party's share.
Name
current_parties.parties[].fraction.numerator
Type
integer
Description
Required when fraction is supplied.
Name
current_parties.parties[].fraction.denominator
Type
non-zero integer
Description
Required when fraction is supplied.

Shared validation rules

Relationship references: trust_creator, initial_trustee, ownership[].owner_id, ownership[].subowners, testator, executor, and current_parties.parties[].contact_id must reference existing contacts by external_id within the same top account.
Self references: Relationship arrays cannot reference the contact being created or updated.
Date format: trust_creation_date and will_creation_date must be valid ISO dates in YYYY-MM-DD format.
State format: governing_state, incorporation_state, and state must be valid two-letter US state abbreviations.
Whitespace-only strings: Optional string fields cannot be blank or whitespace-only.
Immutable update fields: type and external_id cannot be updated.
Empty updates: Update requests must include at least one mutable field for the existing contact type.
Array clearing on update: For trust and will role fields, an empty array can be sent during update to clear that role assignment.
Ownership example: Use { "percentage": 60, "owner_id": "owner-a-external-id" } for a single owner or { "percentage": 40, "subowners": ["owner-a-external-id", "owner-b-external-id"] } for a joint ownership entry.

GETadvisor-api.wealth.com/v1/clients/{wid}/contacts

GETadvisor-api.wealth.com/v1/clients/by-external-id/{external_id}/contacts

List Contacts

The List Contacts call expects a client wid (or a caller-defined external_id) in the URL. It returns the contact cards supported by this API for that client.

Query Parameters

Name
advisor_id
Type
string, optional
Description
Required when your API user can access multiple advisors.
Name
team_id
Type
string, optional
Description
Required when your API user can access multiple advisor teams.

Request

GET

advisor-api.wealth.com/v1/clients/{wid}/contacts

  curl --location --request GET 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/contacts' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxxxxxxxxxxx'

HTTP Status Codes

Name
200
Type
Description
Success - Contacts retrieved successfully
Name
400
Type
Description
Bad Request - Missing required path parameters
Name
403
Type
Description
Forbidden - Access denied
Name
404
Type
Description
Not Found - Client not found
Name
405
Type
Description
Method Not Allowed - Unsupported method for this path
Name
500
Type
Description
Internal Server Error - Unexpected server-side failure

List Contacts Response Object

Name
contacts
Type
array
Description
Array of contact objects. Each item uses the same field names as the Get Contact response object documented below.

Response

{
   "contacts": [
       {
           "id": "individual-card-id",
           "external_id": "external-individual-id",
           "type": "Individual",
           "first_name": "Jane",
           "middle_name": "Q",
           "last_name": "Doe"
       },
       {
           "id": "trust-card-id",
           "external_id": "external-trust-id",
           "type": "Trust",
           "legal_name": "Doe Family Trust",
           "trust_type": "JointRevocableTrust",
           "trust_creator": ["external-individual-id"],
           "initial_trustee": ["external-individual-id"],
           "governing_state": "CA",
           "trust_creation_date": "2020-01-02"
       },
       {
           "id": "entity-card-id",
           "external_id": "external-entity-id",
           "type": "Entity",
           "legal_name": "Smith LLC",
           "incorporation_state": "TX",
           "incorporation_form": "LimitedLiabilityCompany",
           "ownership": [
               {
                   "percentage": 60,
                   "owner_id": "external-individual-id"
               },
               {
                   "percentage": 40,
                   "subowners": ["external-individual-id", "external-trust-id"]
               }
           ]
       },
       {
           "id": "will-card-id",
           "external_id": "external-will-id",
           "type": "Will",
           "legal_name": "Jane Doe Will",
           "will_type": "PourOverWill",
           "governing_state": "FL",
           "will_creation_date": "2026-01-20",
           "testator": ["external-testator-id"]
       },
       {
           "id": "class-card-id",
           "external_id": "external-class-id",
           "type": "Class",
           "legal_name": "Beneficiary Class",
           "current_parties": {
               "is_distributed_evenly": true,
               "parties": [
                   {
                       "contact_id": "external-party-id"
                   }
               }
           ]
       }
   ]
}

POSTadvisor-api.wealth.com/v1/clients/{wid}/contacts

POSTadvisor-api.wealth.com/v1/clients/by-external-id/{external_id}/contacts

Add Contact

The Add Contact call expects a client wid (or a caller-defined external_id) in the URL and a JSON request body describing the new contact card. The body must include external_id, type, and any additional required fields for the selected contact type.

The Add Contact Request Object contains your system's external_id, the contact type, and any type-specific fields documented in the Contact Types And Input Rules section above.

Add Contact Request Object

Name
external_id
Type
string (Max 50)
Description
Required for every contact type. Must be unique within the top account.
Name
type
Type
enum
Description
Required for every contact type. One of Individual, Trust, Entity, Charity, Will, or Class.
Name
type-specific fields
Type
varies by type
Description
Supply only the fields that are valid for the chosen type. See the Contact Types And Input Rules section for the exact required and optional field combinations.

Request

POST

advisor-api.wealth.com/v1/clients/{wid}/contacts

  curl --location 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/contacts' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxxxxxxxxxxx' \
    --data-raw '{
        "external_id": "trust-external-id",
        "type": "Trust",
        "legal_name": "Doe Family Trust",
        "trust_type": "DynastyTrust",
        "trust_creator": ["creator-external-id"],
        "initial_trustee": ["trustee-external-id"],
        "governing_state": "FL",
        "trust_creation_date": "2026-01-20"
    }'

HTTP Status Codes

Name
200
Type
Description
Success - Contact created successfully
Name
400
Type
Description
Bad Request - Missing required parameters or invalid contact payload
Name
403
Type
Description
Forbidden - Access denied
Name
404
Type
Description
Not Found - Client not found
Name
405
Type
Description
Method Not Allowed - Unsupported method for this path
Name
409
Type
Description
Conflict - Contact card with this external_id already exists
Name
422
Type
Description
Unprocessable Entity - Request could not be processed
Name
500
Type
Description
Internal Server Error - Unexpected server-side failure

Add Contact Response Object

Name
id
Type
string
Description
Wealth.com identifier for the newly created contact card.

Response

{
   "id": "contact-card-id"
}

GETadvisor-api.wealth.com/v1/clients/{wid}/contacts/{id}

GETadvisor-api.wealth.com/v1/clients/by-external-id/{external_id}/contacts/{id}

Get Contact

The Get Contact call expects a client wid (or a caller-defined external_id) and contact id in the URL.

Request

GET

advisor-api.wealth.com/v1/clients/{wid}/contacts/{id}

  curl --location --request GET 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/contacts/trust-card-id' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxxxxxxxxxxx'

HTTP Status Codes

Name
200
Type
Description
Success - Contact retrieved successfully
Name
400
Type
Description
Bad Request - Missing required path parameters
Name
403
Type
Description
Forbidden - Access denied
Name
404
Type
Description
Not Found - Client or contact not found
Name
405
Type
Description
Method Not Allowed - Unsupported method for this path
Name
500
Type
Description
Internal Server Error - Unexpected server-side failure

Get Contact Response Object

Name
id
Type
string
Description
Wealth.com contact identifier.
Name
external_id
Type
string (Max 50), optional
Description
Your system's identifier for the contact.
Name
type
Type
enum
Description
Contact type: Individual, Trust, Entity, Charity, Will, or Class.
Name
first_name
Type
string (Max 200), optional
Description
Returned for Individual contacts when present.
Name
middle_name
Type
string (Max 200), optional
Description
Returned for Individual contacts when present.
Name
last_name
Type
string (Max 200), optional
Description
Returned for Individual contacts when present.
Name
legal_name
Type
string (Max 200), optional
Description
Returned for Trust, Entity, Charity, Will, and Class contacts when present.
Name
trust_type
Type
string enum, optional
Description
Returned for Trust contacts when a trust subtype is known.
Name
trust_creator
Type
string array, optional
Description
Returned for Trust contacts when trust creators are available.
Name
initial_trustee
Type
string array, optional
Description
Returned for Trust contacts when initial trustees are available.
Name
governing_state
Type
string, optional
Description
Returned for Trust and Will contacts when present.
Name
trust_creation_date
Type
ISO 8601 date (`YYYY-MM-DD`), optional
Description
Returned for Trust contacts when present.
Name
will_creation_date
Type
ISO 8601 date (`YYYY-MM-DD`), optional
Description
Returned for Will contacts when present.
Name
incorporation_state
Type
string, optional
Description
Returned for Entity contacts when present.
Name
incorporation_form
Type
string enum, optional
Description
Returned for Entity contacts when present.
Name
ownership
Type
array, optional
Description
Returned for Entity contacts when present.
Name
ownership[].owner_id
Type
string, optional
Description
Present when an ownership entry has a single owner.
Name
ownership[].subowners
Type
string array, optional
Description
Present when an ownership entry has multiple joint owners.
Name
ein
Type
integer, optional
Description
Returned for Charity contacts when present.
Name
city
Type
string (Max 100), optional
Description
Returned for Charity contacts when present.
Name
state
Type
string, optional
Description
Returned for Charity contacts when present.
Name
address_formatted
Type
string (Max 200), optional
Description
Returned for Charity contacts when present.
Name
notes
Type
string (Max 5000), optional
Description
Returned for Charity and Class contacts when present.
Name
will_type
Type
string enum, optional
Description
Returned for Will contacts when present.
Name
testator
Type
string array, optional
Description
Returned for Will contacts when available.
Name
executor
Type
string array, optional
Description
Returned for Will contacts when available.
Name
current_parties
Type
object, optional
Description
Returned for Class contacts when present.

Response

{
   "id": "trust-card-id",
   "external_id": "external-trust-id",
   "type": "Trust",
   "legal_name": "Doe Family Trust",
   "trust_type": "JointRevocableTrust",
   "trust_creator": ["external-creator-id"],
   "initial_trustee": ["external-trustee-id"],
   "governing_state": "CA",
   "trust_creation_date": "2020-01-02"
}

PUTadvisor-api.wealth.com/v1/clients/{wid}/contacts/{id}

PUTadvisor-api.wealth.com/v1/clients/by-external-id/{external_id}/contacts/{id}

Update Contact

The Update Contact call expects a client wid (or a caller-defined external_id) and contact id in the URL. The request body may contain only mutable fields for the contact's existing type. Do not send type or external_id in an update request.

The Update Contact Request Object uses the same field names as the create endpoint, but only for mutable fields. Do not send type or external_id in an update request.

Update Contact Request Object

Name
mutable type-specific fields
Type
varies by type
Description
Supply only the fields that belong to the contact's existing type and that you want to change.
Name
type
Type
not allowed
Description
Cannot be updated.
Name
external_id
Type
not allowed
Description
Cannot be updated.
Name
relationship arrays
Type
string array, optional
Description
trust_creator, initial_trustee, testator, and executor may be set to an empty array on update to clear those relationships.

Request

PUT

advisor-api.wealth.com/v1/clients/{wid}/contacts/{id}

  curl --location --request PUT 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/contacts/class-card-id' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic xxxxxxxxxxxxx' \
    --data-raw '{
        "notes": "Children in good standing",
        "current_parties": {
            "is_distributed_evenly": true,
            "parties": [
                {
                    "contact_id": "party-a-external-id",
                    "distribution_percentage": 60
                }
            ]
        }
    }'

HTTP Status Codes

Name
200
Type
Description
Success - Contact updated successfully
Name
400
Type
Description
Bad Request - Missing required path parameters, immutable field update, empty update, or invalid contact payload
Name
403
Type
Description
Forbidden - Access denied
Name
404
Type
Description
Not Found - Client or contact not found
Name
405
Type
Description
Method Not Allowed - Unsupported method for this path
Name
409
Type
Description
Conflict - Contact update conflicts with an existing contact
Name
422
Type
Description
Unprocessable Entity - Request could not be processed
Name
500
Type
Description
Internal Server Error - Unexpected server-side failure

Update Contact Response Object

Name
id
Type
string
Description
Wealth.com identifier for the updated contact card.

Response

{
   "id": "class-card-id"
}

Contact

Contact Types And Input Rules

Common identifiers

Individual

Trust

Valid trust_type values

Entity

Valid incorporation_form values

Charity

Will

Valid will_type values

Class

Shared validation rules

List Contacts

Query Parameters

Request

HTTP Status Codes

List Contacts Response Object

Response

Add Contact

Add Contact Request Object

Request

HTTP Status Codes

Add Contact Response Object

Response

Get Contact

Request

HTTP Status Codes

Get Contact Response Object

Response

Update Contact

Update Contact Request Object

Request

HTTP Status Codes

Update Contact Response Object

Response

Valid `trust_type` values

Valid `incorporation_form` values

Valid `will_type` values