Client Group

This API is for the Client Group resource of the Advisor API on the wealth.com platform. It allows connected systems to programmatically manage client groups within a top account, as well as the contact, asset, and document resources assigned to each client group.

A client group represents a household or reporting unit within a top account (a "family"). Each client group has a name, your system's external_id, and one or two assigned contacts (typically the primary client and, when applicable, their spouse or partner). Contacts, assets, and documents that belong to a client group are managed through the Client Group Resources sub-resource described later on this page.

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

Common Identifiers And Input Rules

List Client Groups

The List Client Groups call expects a top account wid to be passed as part of the URL. It returns the client groups in that top account.

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

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required top-account path parameter"
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "client_groups": [
       {
           "id": "1a098c90-8f7c-4000-b12c-9299bc1ade0e",
           "external_id": "client-group-test-01",
           "name": "Doe Family Group",
           "assigned_contacts": [
               "contact-card-test-sep-18-01",
               "contact-card-test-sep-18-02"
           ]
       },
       {
           "id": "fbfece57-6215-449e-9f7a-7b49a70e9a4b",
           "external_id": "client-group-test-02",
           "name": "John Smith",
           "assigned_contacts": [
               "contact-card-test-sep-19-01"
           ]
       }
   ]
}

Add Client Group

The Add Client Group call expects a top account wid in the URL and a JSON request body describing the new client group. The body must include external_id, name, and assigned_contacts.

Note: if name is set to DEFAULT, the client group will have access to all resources in the containing top account, and adding resources via the API is not required.

  curl --location 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx' \
    --data-raw '{
        "external_id": "client-group-test-01",
        "name": "Doe Family Group",
        "assigned_contacts": [
            "contact-card-test-sep-18-01",
            "contact-card-test-sep-18-02"
        ]
    }'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required parameters", "assigned_contacts must be an array", "assigned_contacts must contain 1 or 2 contact card external_ids", "assigned_contacts[i] must be a non-empty string", "assigned_contacts[i] exceeds maximum length of 255 characters", "assigned_contacts[i] duplicates contact card external_id: ...", or "assigned_contacts[i] references non-existing contact card external_id: ..."
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "1a098c90-8f7c-4000-b12c-9299bc1ade0e",
   "external_id": "client-group-test-01",
   "name": "Doe Family Group",
   "assigned_contacts": [
       "contact-card-test-sep-18-01",
       "contact-card-test-sep-18-02"
   ]
}

Get Client Group

The Get Client Group call expects a top account wid and a client_group_id to be passed as part of the URL. The client_group_id is the Wealth.com id returned by the create or list calls.

  curl --location --request GET 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required parameters" or "Missing required top-account path parameter"
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found" or "Client group not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "1a098c90-8f7c-4000-b12c-9299bc1ade0e",
   "external_id": "client-group-test-01",
   "name": "Doe Family Group",
   "assigned_contacts": [
       "contact-card-test-sep-18-01",
       "contact-card-test-sep-18-02"
   ]
}

Update Client Group

The Update Client Group call expects a top account wid and a client_group_id in the URL. The request body must include at least one of name, external_id, or assigned_contacts. Supplying assigned_contacts fully replaces the existing assigned contacts and must still contain one or two contact external_id values. external_id can only be supplied when the client group does not already have one assigned.

curl --location --request PUT 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxxxxxxxxxxxx' \
  --data-raw '{
      "name": "Updated Doe Family Group",
      "assigned_contacts": [
          "contact-card-test-sep-18-01"
      ]
  }'

HTTP Status Codes

Error Messages

• 400 Bad Request: "At least one of name, external_id, or assigned_contacts must be provided", "external_id cannot be updated once set", or any of the assigned_contacts validation messages listed under Add Client Group
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found" or "Client group not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "1a098c90-8f7c-4000-b12c-9299bc1ade0e",
   "external_id": "client-group-test-01",
   "name": "Updated Doe Family Group",
   "assigned_contacts": [
       "contact-card-test-sep-18-01"
   ]
}

Delete Client Group

The Delete Client Group call expects a top account wid and a client_group_id to be passed as part of the URL.

  curl --location --request DELETE 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required wid or client_group_id path parameter"
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found" or "Client group not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "1a098c90-8f7c-4000-b12c-9299bc1ade0e"
}

Client Group Resources

A client group can hold references to contacts, assets, and documents that belong to it. Each reference is a Client Group Resource and is created, listed, retrieved, or deleted under the parent client group.

Each resource has a type, a target_id that points to an existing contact, asset, or document in the same top account, and your system's external_id for the resource record.

Resource Types And target_id

The type field of a Client Group Resource determines what target_id must reference:

• contact - target_id must equal the external_id of an existing contact in the same top account.
• asset - target_id must equal the external_id of an existing asset in the same top account.
• document - target_id must equal the vault_id of an existing document in the same top account.

The {resource_id} path parameter (used by Get Client Group Resource and Delete Client Group Resource) accepts either the Wealth.com id returned for the resource or your external_id for the resource.

Common Resource Identifiers

List Client Group Resources

The List Client Group Resources call expects a top account wid and a client_group_id to be passed as part of the URL. It returns the contact, asset, and document resources currently assigned to the client group.

  curl --location --request GET 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e/resources/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required target or client_group_id path parameter"
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found" or "Client group not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "resources": [
       {
           "id": "8b1f1b8c-3b06-4d8a-9e83-0bb2b1f0a8a1",
           "external_id": "client-group-resource-test-01",
           "type": "contact",
           "target_id": "contact-card-test-sep-18-01"
       },
       {
           "id": "0b2a8c0a-9d5b-4f8c-bd5a-9c2a7e2c0a02",
           "external_id": "client-group-resource-test-02",
           "type": "asset",
           "target_id": "asset-test-01"
       },
       {
           "id": "3f6c1d7e-2a4b-4c5d-8e9f-1a2b3c4d5e6f",
           "external_id": "client-group-resource-test-03",
           "type": "document",
           "target_id": "53ac20e4-8287-4bd7-b7e7-8f09b056325f"
       }
   ]
}

Add Client Group Resource

The Add Client Group Resource call expects a top account wid and a client_group_id in the URL and a JSON request body describing the new resource. The body must include type, target_id, and external_id.

  curl --location 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e/resources/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx' \
    --data-raw '{
        "type": "contact",
        "target_id": "contact-card-test-sep-18-01",
        "external_id": "client-group-resource-test-01"
    }'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required parameters", "contact target_id not found: ...", or "asset target_id not found: ..."
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found" or "Client group not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "8b1f1b8c-3b06-4d8a-9e83-0bb2b1f0a8a1",
   "external_id": "client-group-resource-test-01",
   "type": "contact",
   "target_id": "contact-card-test-sep-18-01"
}

Get Client Group Resource

The Get Client Group Resource call expects a top account wid, a client_group_id, and a resource_id to be passed as part of the URL. The resource_id value can be either the Wealth.com id returned by create or list, or your external_id for the resource.

  curl --location --request GET 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e/resources/client-group-resource-test-01' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required parameters"
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found", "Client group not found", or "Client group resource not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "8b1f1b8c-3b06-4d8a-9e83-0bb2b1f0a8a1",
   "external_id": "client-group-resource-test-01",
   "type": "contact",
   "target_id": "contact-card-test-sep-18-01"
}

Delete Client Group Resource

The Delete Client Group Resource call expects a top account wid, a client_group_id, and a resource_id to be passed as part of the URL. The resource_id value can be either the Wealth.com id returned by create or list, or your external_id for the resource.

  curl --location --request DELETE 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a/client-groups/1a098c90-8f7c-4000-b12c-9299bc1ade0e/resources/client-group-resource-test-01' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

Error Messages

• 400 Bad Request: "Missing required wid, client_group_id, or resource_id path parameter"
• 403 Forbidden: "Access Denied"
• 404 Not Found: "Container not found", "Client group not found", or "Client group resource not found"
• 500 Internal Server Error: Unexpected server-side failure

{
   "id": "8b1f1b8c-3b06-4d8a-9e83-0bb2b1f0a8a1"
}