Skip to main content

wealthbox

Python wrapper for the Wealthbox CRM API.

Install

pip install wealthbox          # library only
pip install "wealthbox[cli]"   # library + the ``wb`` command line tool

Get an API token from WealthBox: Settings → API Access.

Library usage

import os
from wealthbox import WealthBox

wb = WealthBox(token=os.environ["WEALTHBOX_ACCESS_TOKEN"])
contacts = wb.get_contacts({"type": "Person"})

The library never looks for a token itself — it does not read WEALTHBOX_ACCESS_TOKEN or any .env file. Load the token however you like and pass it as token=. A missing or wrong token shows up as a WealthBoxAPIError with status 401/403 that says so.

Command line (wb)

Save your token once, in a regular terminal:

wb auth set-token        # prompts with hidden input
wb auth test             # -> Authenticated as: <your name>

wb looks for the token in this order:

  1. the WEALTHBOX_ACCESS_TOKEN environment variable

  2. a file you name with wb --env-file PATH ...

  3. ~/.config/wealthbox/credentials.json (written by wb auth set-token, owner-only)

  4. ~/.config/wealthbox/.env

If there’s no terminal to prompt in (scripts, editors, AI agents), use wb auth set-token --from-env PATH or pipe the token into wb auth set-token -.

Upgrading to 0.18

Before 0.18.0, wb also read a .env file in the current directory. It no longer does, because a cloned project’s .env could silently point wb at a different WealthBox workspace. If you kept your token in a project .env, wb will now say it can’t find a token (and point at that file). Fix it once with:

wb auth set-token --from-env .env

or keep using the file explicitly with wb --env-file .env .... The library itself is unaffected; it never read .env files.

See CHANGELOG.md for the other behavior changes in 0.18.0.

Filtering

Filter dicts are passed straight through to the API as query parameters. List/tuple values are auto-converted to key[]=v1&key[]=v2 bracket syntax, which the Wealthbox API treats as OR-filtering for fields documented as array[string] (e.g. tags on /contacts).

# OR-filter by tag — returns contacts having EITHER tag
wb.get_contacts({"tags": ["VIP", "Top 10"]})

For fields documented as scalar string (e.g. contact_type, type), the API does not support multi-value filtering at all and will return HTTP 500 if a list is passed. Fan out client-side instead:

seen, out = set(), []
for ct in ("Client", "Trustee"):
    for c in wb.get_contacts({"type": "Person", "contact_type": ct}):
        if c["id"] not in seen:
            seen.add(c["id"])
            out.append(c)

This caveat exists because Wealthbox’s API takes only the last value of repeated query params (?k=a&k=b → b wins), which is what requests produces by default for list values. The bracket rewrite in api_request makes documented array filters work as expected.

Publishing

Update the version in pyproject.toml, commit, then push a tag vX.Y.Z matching that version. GitHub Actions runs the tests, checks the tag matches pyproject.toml, and publishes to PyPI via Trusted Publishing (no stored token).

Metadata

Release files for wealthbox 0.18.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wealthbox 0.18.2
File Size Uploaded Provenance Actions
wealthbox-0.18.2.tar.gz 44.8 kB With provenance Details for wealthbox-0.18.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wealthbox 0.18.2
File Interpreter ABI Platform Actions
wealthbox-0.18.2-py3-none-any.whl Python 3 none any Details for wealthbox-0.18.2-py3-none-any.whl

Total release size: 98.0 kB

Release files / wealthbox-0.18.2.tar.gz

Download URL wealthbox-0.18.2.tar.gz
Size 44.8 kB
Tags Source
SHA-256 checksum
How to use checksums
ebda8a24de5aaf130b7770f8a9790ac68a98b42efa3a549ab41b62520e0eb1c5
BLAKE2b-256 checksum
How to use checksums
b6f8229e8a7d0f0dae0608157242bc8e2331dfbfb15632e5f10478e8d78616ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / wealthbox-0.18.2-py3-none-any.whl

Download URL wealthbox-0.18.2-py3-none-any.whl
Size 53.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a573830772ed9118d8eaa1ff5c8d1966b0498500cc675e63ae7e30e024a17006
BLAKE2b-256 checksum
How to use checksums
362eb6f350310d69ef2529ce411be5d5afe19ed8b04b4bb7cf094b72b5891532
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for wealthbox 0.18.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wealthbox-0.18.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.18.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page