Contact

This API is for the Contact resource of the Advisor API on the wealth.com platform. It allows connected systems to create, retrieve, list, and update contact cards within a top account. A contact card can represent an individual, trust, entity, charity, will, or class.

Every contact returned by this API has a Wealth.com id. The external_id field is your system's identifier for that contact and is also the value you use when one contact references another contact in request payloads.

All contact endpoints require the same Bearer token authentication described in Authentication.

Contact Types And Input Rules

The Contact resource supports the following values for type:

• Individual
• Trust
• Entity
• Charity
• Will
• Class

Common identifiers

Individual

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

Trust

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

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.

Valid incorporation_form values

• CCorporation
• SCorporation
• DonorAdvisorFund
• LimitedLiabilityCompany
• LimitedPartnership
• PrivateFoundation
• SoleProprietorship
• Other

Charity

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

Will

On create, Will requires both legal_name and will_type.

Valid will_type values

• LastWillAndTestament
• PourOverWill

Class

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

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.

List Contacts

The List Contacts call expects a top account wid to be passed as part of the URL. It returns the contact cards supported by this API in that top account.

  curl --location --request GET 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/contacts/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

{
   "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"
                   }
               }
           ]
       }
   ]
}

Add Contact

The Add Contact call expects a top account wid 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 that contact type.

  curl --location 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/contacts/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer 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

Error Messages

• 400 Bad Request: Missing required fields, invalid enum values, invalid state or date formats, invalid nested objects, or relationship references that do not exist in the same top account
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found"
• 409 Conflict: "Contact card with this external id already exists"
• 500 Internal Server Error: Unexpected server-side failure

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

Get Contact

The Get Contact call expects a top account wid and contact id to be passed as part of the URL. The response uses the same field names that the create and update endpoints accept.

  curl --location --request GET 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/contacts/trust-card-id' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

{
   "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"
}

Update Contact

The Update Contact call expects a top account wid and contact id in the URL. The request body may contain only mutable fields for the contact's existing type.

curl --location --request PUT 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/contacts/class-card-id' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxxxxxxxxxxxx' \
  --data-raw '{
      "notes": "Children in good standing",
      "current_parties": {
          "is_distributed_evenly": true,
          "parties": [
              {
                  "contact_id": "party-a-external-id",
                  "distribution_percentage": 60
              },
              {
                  "contact_id": "party-b-external-id",
                  "fraction": {
                      "numerator": 2,
                      "denominator": 5
                  }
              }
          ]
      }
  }'

HTTP Status Codes

Error Messages

• 400 Bad Request: "type cannot be updated", "external_id cannot be updated", "trust_creation_date is only supported for Trust contact cards", "will_creation_date is only supported for Will contact cards", "At least one mutable field must be provided", or another field-level validation error
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found" or "Contact card not found"
• 500 Internal Server Error: Unexpected server-side failure

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