Skip to content

Getting Started

Installation

Install from PyPI:

pip install assured-py

Or with uv:

uv add assured-py

Development Installation

To contribute or run tests locally:

git clone https://github.com/jhaisley/assured-py.git
cd assured-py
pip install -e ".[dev]"

Configuration

The SDK reads configuration from environment variables, with automatic .env file discovery via python-dotenv.

Required Environment Variables

Create a .env file in your project root:

ASSURED_BASE_URL=https://demo-backend.withassured.com
ASSURED_API_KEY=your-api-key-here
ASSURED_USER=your-email@example.com
ASSURED_PASS=your-password
Variable Required Description
ASSURED_BASE_URL Yes Base URL of the Assured backend
ASSURED_API_KEY Yes API key sent via the x-api-key header
ASSURED_USER For JWT endpoints Email for programmatic login
ASSURED_PASS For JWT endpoints Password for programmatic login

When are credentials needed?

The API Key handles the vast majority of requests. However, certain undocumented endpoints — file uploading, SSN encryption, and document association — require user credentials (ASSURED_USER / ASSURED_PASS) to acquire an internal JWT session token. The client handles this transparently.

.env File Discovery

The SDK uses find_dotenv(usecwd=True) to locate your .env file, starting from the current working directory of your script. It will log the path it found:

Loaded environment variables from: /path/to/your/project/.env
✅ Successfully found credentials for user@example.com

Your First Request

import asyncio
from assured import AssuredClient

async def main():
    async with AssuredClient() as client:
        # List all providers
        providers = await client.providers.list_all()
        for p in providers:
            print(f"{p.full_name} — NPI: {p.npi}")

asyncio.run(main())

Using the Context Manager

AssuredClient is designed to be used as an async context manager, which ensures the underlying HTTP connection pool is properly cleaned up:

async with AssuredClient() as client:
    # All your API calls here
    ...
# Connection pool is automatically closed

You can also manage the lifecycle manually:

client = AssuredClient()
try:
    providers = await client.providers.list_all()
finally:
    await client.close()

Looking Up a Provider by NPI

Since Assured doesn't offer a native NPI search endpoint, the SDK provides get_by_npi() which fetches the full provider list and caches it for 5 minutes:

provider = await client.providers.get_by_npi("1234567890")
print(f"{provider.full_name} — {provider.email}")

# Subsequent calls within 5 minutes hit the cache — no extra API calls
another = await client.providers.get_by_npi("0987654321")

Tip

The cache is per-client instance. If you need fresh data, create a new AssuredClient.

What's Next?