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:
the WEALTHBOX_ACCESS_TOKEN environment variable
a file you name with wb --env-file PATH ...
~/.config/wealthbox/credentials.json (written by wb auth set-token, owner-only)
~/.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.