Top Account

This API is for the Top Account resource of the Advisor API on the wealth.com platform. It allows connected systems to programmatically manage top accounts. Note: Deleting top accounts via API is currently not supported (given the irreversible nature of that operation).

A "top account" is a family in the largest sense; within a top account, you will be able to create one or more client groups, which would represent separate households or reporting groups within that top account (family).

GETadvisor-api.wealth.com/v2/top-accounts/{wid}

Get Top Account

The Get Top Account call expects a Wealth.com Id (wid) to be passed as part of the URL. The wid is unique to each top account.

Request

GET

advisor-api.wealth.com/v2/top-accounts/{wid}

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

HTTP Status Codes

Name
200
Type
Description
Success - Top account retrieved successfully
Name
400
Type
Description
Bad Request - Missing required parameter wid
Name
403
Type
Description
Forbidden - User is not authorized to access this resource with an explicit deny
Name
404
Type
Description
Not Found - Top account not found
Name
500
Type
Description
Internal Server Error - Server error occurred while retrieving top account

Error Messages

400 Bad Request: "Missing required parameters"
403 Forbidden: "User is not authorized to access this resource with an explicit deny"
500 Internal Server Error: "Internal server error"

Get Top Account Response Object

Name
wid
Type
string (Max 64)
Description
Wealth.com unique identifier for the top account.
Name
external_id
Type
string (Max 255)
Description
Your firm's unique identifier for the top account.
Name
name
Type
string (Max 255)
Description
The name of the top account.

Response

{
   "wid": "786bb91c-35ec-49bb-bc28-1d2930d7db6a",
   "external_id": "cn4910ny98ec9vb3ghj",
   "name": "Doe Family"
}

GETadvisor-api.wealth.com/v2/top-accounts/

List Top Accounts

The List Top Accounts call retrieves all top accounts accessible to the authenticated user. It returns a paginated array of top accounts.

Query Parameters

Name
page
Type
integer, optional
Description
The page number to retrieve. Defaults to 1 if not specified.
Name
limit
Type
integer, optional
Description
The number of top accounts per page. Must be between 1 and 100. Defaults to 20 if not specified.

Request

GET

advisor-api.wealth.com/v2/top-accounts/

  curl --location --request GET 'https://advisor-api.wealth.com/v2/top-accounts/?page=1&limit=10' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx'

HTTP Status Codes

Name
200
Type
Description
Success - Top accounts retrieved successfully
Name
400
Type
Description
Bad Request - Missing required parameters
Name
403
Type
Description
Forbidden - User is not authorized to access this resource with an explicit deny
Name
500
Type
Description
Internal Server Error - Server error occurred while retrieving top accounts

Error Messages

400 Bad Request: "Missing required parameters"
403 Forbidden: "User is not authorized to access this resource with an explicit deny"
500 Internal Server Error: "Internal server error"

List Top Accounts Response Object

Name
top_accounts
Type
array
Description
An array of top account objects. Each object has the same structure as the Get Top Account response object.
Name
pagination
Type
object
Description
Pagination metadata for the response.
Name
pagination.page
Type
integer
Description
The current page number.
Name
pagination.limit
Type
integer
Description
The number of top accounts per page.
Name
pagination.total_count
Type
integer
Description
The total number of top accounts available.
Name
pagination.total_pages
Type
integer
Description
The total number of pages available, given the limit used.

Response

{
   "top_accounts": [
       {
           "wid": "d36df251-1395-463e-9866-655ce2949ea3",
           "external_id": "07172",
           "name": "Test Container 1"
       },
       {
           "wid": "86982a7e-88e5-43f0-a30f-c6fc7a37594b",
           "external_id": "07173",
           "name": "Test Container 2"
       },
       {
           "wid": "c9fd3e44-1f20-4611-a01d-24626144c993",
           "external_id": "07174",
           "name": "Test Container 3"
       }
   ],
   "pagination": {
       "page": 1,
       "limit": 10,
       "total_count": 25,
       "total_pages": 3
   }
}

POSTadvisor-api.wealth.com/v2/top-accounts/

Add Top Account

The Add Top Account Request Object model contains your firm's unique identifier for the top account as well as the top account name.

Add Top Account Request Object

Name
external_id
Type
string (Max 255)
Description
Your firm's unique identifier for the top account.
Name
name
Type
string (Max 255)
Description
The name of the top account.

Request

POST

advisor-api.wealth.com/v2/top-accounts

  curl --location 'https://advisor-api.wealth.com/v2/top-accounts/' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer xxxxxxxxxxxxx' \
    --data-raw '{
        "external_id": "cn4910ny98ec9vb3ghj",
        "name": "Doe Family"
    }'

HTTP Status Codes

Name
200
Type
Description
Success - Top account created successfully
Name
400
Type
Description
Bad Request - Missing required parameters
Name
403
Type
Description
Forbidden - User is not authorized to access this resource with an explicit deny
Name
409
Type
Description
Conflict - Top account with same name or external_id already exists
Name
500
Type
Description
Internal Server Error - Server error occurred while creating top account

Error Messages

400 Bad Request: "Missing required parameters"
403 Forbidden: "User is not authorized to access this resource with an explicit deny"
409 Conflict: "Container with this name already exists" or "Container with this externalId already exists"
500 Internal Server Error: "Internal server error"

Add Top Account Response Object

Name
wid
Type
string (Max 64)
Description
Wealth.com unique identifier for the top account.
Name
external_id
Type
string (Max 255)
Description
Your firm's unique identifier for the top account.
Name
name
Type
string (Max 255)
Description
The name of the top account.

Response

{
   "wid": "786bb91c-35ec-49bb-bc28-1d2930d7db6a",
   "external_id": "cn4910ny98ec9vb3ghj",
   "name": "Doe Family"
}

PUTadvisor-api.wealth.com/v2/top-accounts/{wid}

Update Top Account

The Update Top Account Object model contains your firm's unique identifier for the top account as well as the top account name.

Update Top Account Request Object

Name
external_id
Type
string (Max 255), optional
Description
Your firm's unique identifier for the top account.
Name
name
Type
string (Max 255), optional
Description
The name of the top account.

Request

PUT

advisor-api.wealth.com/v2/top-accounts/{wid}

curl --location 'https://advisor-api.wealth.com/v2/top-accounts/786bb91c-35ec-49bb-bc28-1d2930d7db6a' -X PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer xxxxxxxxxxxxx' \
  --data-raw '{
      "name": "Doe-Jones Family"
    }'

HTTP Status Codes

Name
200
Type
Description
Success - Top account updated successfully
Name
400
Type
Description
Bad Request - Missing required parameter wid or no update fields provided
Name
403
Type
Description
Forbidden - User is not authorized to access this resource with an explicit deny
Name
404
Type
Description
Not Found - Top account not found
Name
409
Type
Description
Conflict - Top account with same name or external_id already exists
Name
500
Type
Description
Internal Server Error - Server error occurred while updating top account

Error Messages

400 Bad Request: "Missing required parameters" or "At least one of name or external_id must be provided"
403 Forbidden: "User is not authorized to access this resource with an explicit deny"
409 Conflict: "Container with this name already exists" or "Container with this externalId already exists"
500 Internal Server Error: "Internal server error"

Update Top Account Response Object

See the Get Top Account response object.