Document
This API is for the Document resource of the Advisor API on the wealth.com platform. It allows connected systems to programmatically manage documents for a client.
If your API user has access to multiple advisors, include advisor_id and team_id as query parameters on document requests. These client-scoped paths also accept the client's external_id in place of wid — see Addressing a client.
All client document operations accept M2M bearer tokens. See M2M Authentication.
List Documents
The List Documents call expects a client wid (or a caller-defined external_id) in the URL. It returns a paginated array of documents for that client. You can optionally filter results by passing a tags query parameter containing a comma-separated list of tag names.
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.
- Name
limit- Type
- integer, optional
- Description
The number of documents to retrieve. Must be between 1 and 1000.
- Name
nextToken- Type
- string, optional
- Description
Token for pagination to retrieve the next set of results.
- Name
tags- Type
- string, optional
- Description
Optional comma-separated list of tag names to filter by, for example
tags=current,funded.
Request
curl --location --request GET 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/documents?limit=10&tags=current,funded' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxx'
HTTP Status Codes
- Name
200- Type
- Description
- Success - Documents retrieved successfully
- Name
400- Type
- Description
- Bad Request - Missing or invalid request parameters
- Name
403- Type
- Description
- Forbidden - Access denied
- Name
404- Type
- Description
- Not Found - Client not found
- Name
422- Type
- Description
- Unprocessable Entity - Request could not be processed
- Name
500- Type
- Description
- Internal Server Error - Unexpected server-side failure
List All Documents Response Object
- Name
documents- Type
- array
- Description
An array of document objects. Each object has the same structure as the Get Document response object (except
file_statusfield - for that you'll need to call Get Document individually).
- Name
pagination- Type
- object
- Description
Pagination metadata for the response.
- Name
pagination.total_count- Type
- integer
- Description
The total number of documents available.
Response
{
"documents": [
{
"wid": "786bb91c-35ec-49bb-bc28-1d2930d7db6a",
"vault_id": "67bd31f5-9398-5ce8-cd39-2e4041e8db7b",
"name": "jane-doe-trust",
"extension": "pdf",
"description": "Jane Doe Trust",
"category": "estate_planning",
"sub_category": "revocable_trusts_and_supporting_documents",
"tags": ["funded"],
"creation_date": "2024-02-03T14:15:22Z",
"modification_date": "2024-02-07T09:33:15Z"
},
{
"wid": "786bb91c-35ec-49bb-bc28-1d2930d7db6a",
"vault_id": "53ac20e4-8287-4bd7-b7e7-8f09b056325f",
"name": "john-doe-slat",
"extension": "pdf",
"description": "John Doe SLAT",
"category": "estate_planning",
"sub_category": "irrevocable_trusts",
"type": "slat",
"tags": ["current", "reviewed"],
"creation_date": "2024-02-01T07:23:12Z",
"modification_date": "2024-02-05T02:11:48Z"
}
],
"pagination": {
"total_count": 25
}
}
Upload Document
The Upload Document call expects a client wid (or a caller-defined external_id) in the URL and a JSON request body describing the document metadata. A new or retryable upload response includes an upload_uri; use it to upload the file content as described in Using Upload URI.
Upload Document Request Object
- Name
external_id- Type
- string (Max 255), optional
- Description
A caller-defined identifier for this document, used as an idempotency key within the client or top account. Repeating the request with the same
external_idand document identity returns the existingvault_id. The response includes a newupload_urionly if the file still needs to be uploaded or retried; completed documents cannot be overwritten through a replay. If this route contains anexternal_idpath parameter, the path value identifies the client and this body value identifies the document.
- Name
name- Type
- string (Max 200)
- Description
The file name of the document to be uploaded.
- Name
extension- Type
- string (Max 32)
- Description
The file extension of the document to be uploaded. See File Upload Requirements for supported extensions.
- Name
description- Type
- string (Max 2000), optional
- Description
The description for the document.
- Name
category- Type
- string enum
- Description
The category for the document. See Category Sub-Category Type Values for enum values.
- Name
sub_category- Type
- string enum
- Description
The sub-category for the document. See Category Sub-Category Type Values for enum values.
- Name
type- Type
- string enum, optional
- Description
The type for the document. See Category Sub-Category Type Values for enum values.
- Name
tags- Type
- string array, optional
- Description
An array of tag names to associate with the document. See Supported Tag Values for the built-in values documented by this API. If any supplied tag is not valid for the current account context, the request returns
400 Invalid tags: ....
- Name
start_ester_job- Type
- boolean, optional
- Description
When true, estate document analysis starts after the file is uploaded. The response includes
correlation_id. Completion is delivered as EsterJobCompleted.
- Name
start_tax_job- Type
- boolean, optional
- Description
When true, tax document analysis starts after the file is uploaded. The response includes
correlation_id. Completion is delivered as TaxJobCompleted. Cannot be combined withstart_ester_job. Sending both returns400.
Request
curl --location 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxx' \
--data-raw '{
"external_id": "partner-document-123",
"name": "john-doe-slat",
"extension": ".pdf",
"description": "John Doe SLAT",
"category": "estate_planning",
"sub_category": "irrevocable_trusts",
"type": "slat",
"tags": ["current", "reviewed"]
}'
HTTP Status Codes
- Name
200- Type
- Description
- Success - Document metadata created or replayed; an upload URI is returned when file upload is still required
- Name
400- Type
- Description
- Bad Request - Missing required fields or invalid document metadata
- Name
403- Type
- Description
- Forbidden - Access denied
- Name
405- Type
- Description
- Method Not Allowed - Unsupported method for this path
- Name
409- Type
- Description
- Conflict - The supplied document
external_idis already associated with different document metadata
- Name
422- Type
- Description
- Unprocessable Entity - Request could not be processed
- Name
500- Type
- Description
- Internal Server Error - Unexpected server-side failure
- Name
503- Type
- Description
- Service Unavailable - A concurrent request prevented the document from being created; retry the request
Upload Document Response Object
- Name
wid- Type
- string (Max 64)
- Description
Wealth.com unique identifier for the top account.
- Name
vault_id- Type
- string (Max 64)
- Description
Wealth.com unique identifier for the document.
- Name
upload_uri- Type
- string (Max 2000), optional on replay
- Description
A secure link to upload the file. Omitted when an idempotent replay finds that the document upload is already complete. See Using Upload URI for detailed upload instructions.
- Name
correlation_id- Type
- string, optional
- Description
Present when
start_ester_joborstart_tax_jobis true. Identifies this analysis run. The same value is sent asPayload.CorrelationIdon the completion webhook.
Response
{
"wid": "786bb91c-35ec-49bb-bc28-1d2930d7db6a",
"vault_id": "53ac20e4-8287-4bd7-b7e7-8f09b056325f",
"upload_uri": "https://vault.files.wealth.com/upload/..."
}
Get Document
The Get Document call expects a client wid (or a caller-defined external_id) and document vault_id in the URL. Once document metadata exists, this endpoint returns 200 throughout the upload lifecycle. A 404 means the client or document metadata does not exist or has been deleted.
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.
- Name
include_ester_outputs- Type
- boolean, optional
- Description
When true on an estate planning document, the response includes
ester_outputsandflowchart_pdf_download_uriwhen those artifacts exist.
Request
curl --location --request GET 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/documents/53ac20e4-8287-4bd7-b7e7-8f09b056325f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxx'
HTTP Status Codes
- Name
200- Type
- Description
- Success - Document 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 document 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 Document Response Object
- Name
wid- Type
- string (Max 64)
- Description
Wealth.com unique identifier for the top account.
- Name
vault_id- Type
- string (Max 64)
- Description
Wealth.com unique identifier for the document.
- Name
name- Type
- string (Max 200)
- Description
The file name of the document.
- Name
extension- Type
- string (Max 32)
- Description
The file extension of the document. See File Upload Requirements for supported extensions.
- Name
description- Type
- string (Max 2000), optional
- Description
The description for the document (if provided).
- Name
category- Type
- string enum
- Description
The category for the document. See Category Sub-Category Type Values for enum values.
- Name
sub_category- Type
- string enum
- Description
The sub-category for the document. See Category Sub-Category Type Values for enum values.
- Name
type- Type
- string enum, optional
- Description
The type for the document (if provided). See Category Sub-Category Type Values for enum values.
- Name
tags- Type
- string array, optional
- Description
An array of tag names associated with the document. See Supported Tag Values for the built-in values documented by this API.
- Name
creation_date- Type
- ISO 8601 date-time
- Description
The UTC timestamp when the document was created within the Wealth.com Vault.
- Name
modification_date- Type
- ISO 8601 date-time
- Description
The UTC timestamp when the document was last modified within the Wealth.com Vault.
- Name
file_status- Type
- string enum
- Description
The upload status of the file. Continue polling while it is
AwaitingUpload,Processing, orCategorizing.Uploadedis terminal success.Failedmeans the current upload attempt failed or timed out and can be retried. Possible values are:'AwaitingUpload' 'Processing' 'Categorizing' 'Failed' 'Uploaded'
- Name
download_uri- Type
- string, optional
- Description
A secure presigned URI to download the file. This field is included only when the encrypted file is available. A document in
Categorizingmay include it.
- Name
ester_outputs- Type
- array, optional
- Description
Present when
include_ester_outputsis true and generated estate analysis documents exist. Flowchart outputs are omitted. Each entry is a pointer. Retrieve the file with Get Document onester_outputs.vault_id, then a plain GET on that response'sdownload_uri.- Name
vault_id- Type
- string
- Description
Wealth.com unique identifier for the generated document.
- Name
type- Type
- string
- Description
One of
StandardExecSummary,AdvancedExecSummary,Insights.
- Name
extension- Type
- string
- Description
File extension of the generated document.
- Name
creation_date- Type
- ISO 8601 date-time
- Description
The UTC timestamp when the generated document was created.
- Name
modification_date- Type
- ISO 8601 date-time
- Description
The UTC timestamp when the generated document was last modified.
- Name
flowchart_pdf_download_uri- Type
- string, optional
- Description
Present for an estate planning document when
include_ester_outputsis true and a disposition flowchart PDF exists. A plain GET on the URI returns the file.
- Name
tax_artifact_download_uri- Type
- string, optional
- Description
Present for a tax document when a generated tax artifact PDF exists. A plain GET on the URI returns the file.
- Name
tax_artifact- Type
- object, optional
- Description
The tax analysis JSON, when available for a tax document. The PDF is
tax_artifact_download_uri.
Response
{
"wid": "786bb91c-35ec-49bb-bc28-1d2930d7db6a",
"vault_id": "53ac20e4-8287-4bd7-b7e7-8f09b056325f",
"name": "john-doe-slat",
"extension": "pdf",
"description": "John Doe SLAT",
"category": "estate_planning",
"sub_category": "irrevocable_trusts",
"type": "slat",
"tags": ["current", "reviewed"],
"creation_date": "2024-02-01T07:23:12Z",
"modification_date": "2024-02-05T02:11:48Z",
"file_status": "Uploaded",
"download_uri": "https://vault.files.wealth.com/download/..."
}
Update Document
The Update Document call expects a client wid (or a caller-defined external_id) and document vault_id in the URL. The request body may contain any supported mutable document metadata fields.
If an upload has file_status: Failed, or has file_status: AwaitingUpload and its previous upload_uri has expired, call this endpoint for the existing vault_id to obtain a new upload_uri instead of creating another document. Send an empty JSON object when no metadata changes are needed, then PUT the file to the replacement URI.
Update Document Request Object
- Name
name- Type
- string (Max 200), optional
- Description
The file name of the document.
- Name
extension- Type
- string (Max 32), optional
- Description
The file extension of the document. See File Upload Requirements for supported extensions.
- Name
description- Type
- string (Max 2000), optional
- Description
The description for the document.
- Name
category- Type
- string enum, optional
- Description
The category for the document. See Category Sub-Category Type Values for enum values.
- Name
sub_category- Type
- string enum, optional
- Description
The sub-category for the document. See Category Sub-Category Type Values for enum values.
- Name
type- Type
- string enum, optional
- Description
The type for the document. See Category Sub-Category Type Values for enum values.
- Name
tags- Type
- string array, optional
- Description
An array of tag names to associate with the document. See Supported Tag Values for the built-in values documented by this API. If any supplied tag is not valid for the current account context, the request returns
400 Invalid tags: ....
Request
curl --location 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/documents/53ac20e4-8287-4bd7-b7e7-8f09b056325f' -X PATCH \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxx' \
--data-raw '{
"name": "john-doe-slat-revised",
"description": "John Doe SLAT Revised",
"tags": ["current", "ready-to-publish", "reviewed"]
}'
HTTP Status Codes
- Name
200- Type
- Description
- Success - Document updated successfully
- Name
400- Type
- Description
- Bad Request - Missing required path parameters or invalid document metadata
- Name
403- Type
- Description
- Forbidden - Access denied
- Name
404- Type
- Description
- Not Found - Client or document not found
- Name
405- Type
- Description
- Method Not Allowed - Unsupported method for this path
- Name
422- Type
- Description
- Unprocessable Entity - Request could not be processed
- Name
500- Type
- Description
- Internal Server Error - Unexpected server-side failure
Update Document Response Object
- Name
wid- Type
- string (Max 64)
- Description
Wealth.com unique identifier for the top account.
- Name
vault_id- Type
- string (Max 64)
- Description
Wealth.com unique identifier for the document.
- Name
name- Type
- string (Max 200)
- Description
The file name of the document.
- Name
extension- Type
- string (Max 32)
- Description
The file extension of the document. See File Upload Requirements for supported extensions.
- Name
description- Type
- string (Max 2000), optional
- Description
The description for the document (if provided).
- Name
category- Type
- string enum
- Description
The category for the document. See Category Sub-Category Type Values for enum values.
- Name
sub_category- Type
- string enum
- Description
The sub-category for the document. See Category Sub-Category Type Values for enum values.
- Name
type- Type
- string enum, optional
- Description
The type for the document (if provided). See Category Sub-Category Type Values for enum values.
- Name
tags- Type
- string array, optional
- Description
An array of tag names associated with the document. See Supported Tag Values for the built-in values documented by this API.
- Name
creation_date- Type
- ISO 8601 date-time
- Description
The UTC timestamp when the document was created within the Wealth.com Vault.
- Name
modification_date- Type
- ISO 8601 date-time
- Description
The UTC timestamp when the document was last modified within the Wealth.com Vault.
- Name
upload_uri- Type
- string (Max 2000)
- Description
A secure link to upload a new file. See Using Upload URI for detailed upload instructions.
Delete Document
The Delete Document call expects a client wid (or a caller-defined external_id) and document vault_id in the URL.
Request
curl --location --request DELETE 'https://advisor-api.wealth.com/v1/clients/2d6fb3ee-1617-4ee2-b402-6dd0e4449c85/documents/53ac20e4-8287-4bd7-b7e7-8f09b056325f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic xxxxxxxxxxxxx'
HTTP Status Codes
- Name
200- Type
- Description
- Success - Document deleted 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 document 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
Delete Document Response Object
- Name
message- Type
- string, optional
- Description
Error message (if any).
Response
{
"message": "Vault doesn't exist"
}
Using Upload URI
After creating a document using the Upload Document endpoint or updating a document using the Update Document endpoint, you'll receive an upload_uri in the response. Send the file content directly to this temporary upload URL. The URL authorizes the upload, so the PUT request does not require an Authorization header or other Advisor API credentials.
Upload Process
- Create/Update Document: First, create or update a document using the respective API endpoints to get an
upload_uri - Upload File Content: Use the
upload_uriwith an unauthenticated PUT request to upload the actual file content - Verify Upload: Poll the Get Document endpoint until
file_statusisUploadedorFailed.Uploadedis terminal success. If the attempt isFailed, PATCH the existing document with{}to obtain a replacementupload_uri, PUT the file again, and resume polling.
File Upload Requirements
- Maximum File Size: 100 MiB (104,857,600 bytes)
- Supported File Extensions:
.bmp,.png,.jpg,.jpeg,.pdf,.doc,.docx,.xls,.xlsx,.csv,.tsv,.ppt,.pptx,.key - Content-Type Header: Required for PUT uploads. Use the supported value for the file format shown below.
- Content-Length Header: Required and must equal the file size in bytes. Chunked transfer encoding is not supported. Most HTTP clients, including cURL when using
--data-binary @file, set this header automatically.
Content-Type Mappings
| File Extension | Content-Type |
|---|---|
.pdf | application/pdf |
.doc | application/msword |
.docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document |
.xls | application/vnd.ms-excel |
.xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
.ppt | application/vnd.ms-powerpoint |
.pptx | application/vnd.openxmlformats-officedocument.presentationml.presentation |
.key | application/x-iwork-keynote-sffkey |
.csv | text/csv |
.tsv | text/tab-separated-values |
.png | image/png |
.jpg | image/jpeg |
.jpeg | image/jpeg |
.bmp | image/bmp |
Upload Example
File Upload
curl --location --request PUT 'https://vault.files.wealth.com/upload/v2_e55995bc-1227-4f10-9f78-b737fba5287d/39405749-021d-4d7e-a1a1-ababb505a5e5?Expires=1757605771&Signature=hLT8xbANPOYo6k0GhTe76izvSLLFBLMqdayK0D1dNhhouFGwgTywfqwXQ7thTtGRcQCX~35aIGhH0ZO1Zs7O2SIRN~2MTuv6-dyc5v-~P3xgGZUbfo~hW8tbhKZp-F5bDz2dTezkyT-PDZZjfsW5qM~0NbsJn3Ag0w0mhFPFVPlh1LeAJbKl9tit8uA9ZtxagfGvYihr4P3CvcVqKTw51ZrrjMuISnBRWMkBjKx7uox7nyyXXeMPot8dhoPRt4pWLTJKIj3DRDWRdeIcjyCu8irdI4v4uUUn-xJM7Ts5v0bBz3xd2Nv05u9OMp6-3S2ssvVhkhF~9XTMgA00nlW29A__&Key-Pair-Id=K19U4LCWXRW7C3' \
--header 'Content-Type: application/pdf' \
--data-binary '@/Users/user/Downloads/sample.pdf'
Important Notes
- The
upload_uriexpires after 5 minutes. Use it promptly after receiving it. - The
upload_uriprovides authorization for the upload. Do not send anAuthorizationheader with the PUT request. - Supply a document
external_idwhen creating a document so the create request can be retried safely if its response is not received. A matching retry returns the originalvault_id; it returns a newupload_urionly while the file still needs to be uploaded or retried. - Always include the supported
Content-Typeheader for the uploaded file format. - File validation and processing are asynchronous. A successful PUT only confirms that the file was transferred. Poll Get Document until
file_statusisUploadedor the current attempt isFailed; retry failed attempts through PATCH. - Use
download_urionly when it is present. It is omitted until the encrypted file is available, including during file-availability races.
Supported Tag Values
The following built-in tag names are supported across teams and top accounts. Your organization may also have additional team-specific custom tags in Vault, but the values below are the standard tags documented by this API.
| Tag Name | Description |
|---|---|
current | Current |
duplicate | Duplicate |
family-office-report | Family Office Report |
funded | Funded |
needs-review | Needs Review |
not-signed | Not Signed |
ready-to-publish | Ready to Publish |
reviewed | Reviewed |
snapshot-report | Snapshot Report |
superseded | Superseded |
unfunded | Unfunded |
Category Sub-Category Type Values
| Category | Sub-Category | Type |
|---|---|---|
| personal_information | birth_certificate | — |
| personal_information | driver_license | — |
| personal_information | passport | — |
| personal_information | visa | — |
| personal_information | tsa_pre_global_entry | — |
| personal_information | airline_frequent_flyers | — |
| personal_information | name_change_orders | — |
| personal_information | medical_identification_cards | — |
| personal_information | military_discharge_papers | — |
| personal_information | personal_information_other | — |
| family | marriage_certificate | — |
| family | marital_agreement | — |
| family | divorce_decree | — |
| family | domestic_partnership_certificate | — |
| family | adoption_decree | — |
| family | death_certificate | — |
| family | family_other | — |
| estate_planning | last_will_and_testament | — |
| estate_planning | revocable_trusts_and_supporting_documents | — |
| estate_planning | revocable_trusts_and_supporting_documents | pour_over_will |
| estate_planning | irrevocable_trusts | — |
| estate_planning | irrevocable_trusts | dynasty_trust |
| estate_planning | irrevocable_trusts | slat |
| estate_planning | irrevocable_trusts | grat |
| estate_planning | irrevocable_trusts | ilit |
| estate_planning | irrevocable_trusts | crut |
| estate_planning | irrevocable_trusts | qprt |
| estate_planning | irrevocable_trusts | other |
| estate_planning | living_will | — |
| estate_planning | durable_power_of_attorney | — |
| estate_planning | nomination_of_guardianship | — |
| estate_planning | letters_of_intent | — |
| estate_planning | personal_inventory_list | — |
| estate_planning | beneficiary_designations | — |
| estate_planning | insurance_policies | — |
| estate_planning | charitable_giving | — |
| estate_planning | estate_planning_other | — |
| estate_planning | presentation_materials | — |
| estate_planning | llc_operating_agreement | — |
| assets | real_estate_leases_deeds | — |
| assets | investments | — |
| assets | storage_units | — |
| assets | safe_deposit_boxes | — |
| assets | gun_permits | — |
| assets | assets_other | — |
| taxes | 1099 | — |
| taxes | tax_return_1040 | — |
| taxes | w2 | — |
| taxes | k1s | — |
| taxes | form_8949_crypto | — |
| taxes | form_709_gift_tax_returns | — |
| taxes | form_1098s_debt | — |
| taxes | taxes_other | — |
| business | employment_contract | — |
| business | options_agreements | — |
| business | ndas | — |
| business | partnership_agreements | — |
| business | corporations | — |
| business | employee_benefits | — |
| business | performance_reviews | — |
| business | business_other | — |
| miscellaneous | uncategorized | — |
| miscellaneous | miscellaneous_other | — |