Skip to main content

headshotmarketing-sdk

Official Python SDK for Headshotmarketing — an end-to-end marketing platform on the Burdenoff platform.

Pre-launch notice: Headshotmarketing is launching in 2026. This package is published ahead of general availability so integrators can build early. There is no live production service yet — join the waitlist at headshotmarketing.com to get early access.

This SDK is a thin shell over burdenoff-sdk-libs. It mounts the shared platform modules plus the Headshotmarketing domain module and a standalone sandbox module, and exposes them as one ergonomic, fully typed client.

Features

  • Async/await throughout, built on httpx
  • Dual-endpoint GraphQL client (workspace + global gateways)
  • 23 mounted modules: the shared generic set + headshotmarketing + sandbox
  • Multiple auth flows: email/password, device code, PKCE, client credentials
  • Automatic token refresh
  • Typed error hierarchy
  • Full type hints with py.typed marker

Installation

pip install headshotmarketing-sdk

# Development install
pip install -e ".[dev]"

Quick Start

import asyncio
from headshotmarketing_sdk import HeadshotmarketingSDK


async def main():
    # Defaults to the shared prod gateways. Override the endpoints (or set
    # HEADSHOTMARKETING_*_ENDPOINT / BURDENOFF_*_ENDPOINT env vars) for local dev.
    sdk = HeadshotmarketingSDK()

    # Sign in with email/password
    await sdk.auth.sign_in(email="user@example.com", password="secret")

    # Headshotmarketing-domain operations are nested under sdk.headshotmarketing
    campaigns = await sdk.headshotmarketing.campaigns.list()
    leads = await sdk.headshotmarketing.leads.list()

    # Shared cross-product modules are mounted at the top level
    tags = await sdk.tags.list()

    await sdk.close()


asyncio.run(main())

Nested namespace

Per the platform mandate (no compatibility shim), every module surface is nested under its owning module. The Headshotmarketing domain bundle keeps its sub-entities nested:

await sdk.headshotmarketing.campaigns.list()
await sdk.headshotmarketing.leads.list()
await sdk.headshotmarketing.contacts.list()
await sdk.headshotmarketing.deals.list()
await sdk.headshotmarketing.pipelines.list()
await sdk.headshotmarketing.content.list()
await sdk.headshotmarketing.social.list()
await sdk.headshotmarketing.ads.list()
await sdk.headshotmarketing.seo.list()
await sdk.headshotmarketing.workflows.list()

Modules

All methods are async. The following modules are mounted on the HeadshotmarketingSDK instance: auth, billing, channels, conversations, devportal, export, files, groups, health, integrations, headshotmarketing, notifications, organizations, products, rbac, sandbox, scheduler, security, store, support, tags, tours, workspaces.

Configuration

from headshotmarketing_sdk import HeadshotmarketingSDK

sdk = HeadshotmarketingSDK(
    workspace_endpoint="https://graphqlworkspaces.burdenoff.com/workspaces/graphql",
    global_endpoint="https://graphql.burdenoff.com/global/graphql",
    client_id="burdenoff_cli_headshotmarketing",
    oidc_issuer=None,                       # derived from global_endpoint
    api_key=None,
    access_token=None,
    refresh_token=None,
    workspace_token=None,
    timeout=30.0,
    auto_refresh=True,
)

Error Handling

from headshotmarketing_sdk import (
    HeadshotmarketingError,
    AuthenticationError,
    AuthorizationError,
    NetworkError,
    ValidationError,
    RateLimitError,
    DeviceCodeExpiredError,
    DeviceCodeDeniedError,
)

try:
    await sdk.auth.sign_in(email="user@example.com", password="wrong")
except AuthenticationError:
    print("Invalid credentials")
except NetworkError:
    print("Could not reach the API")
except HeadshotmarketingError as e:
    print(f"SDK error: {e}")

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

make format        # black + isort
make lint          # flake8
make type-check    # mypy (strict)
make test          # pytest
make sanity        # format-check + lint + type-check + test (cov>=80) + build

License

Proprietary — Copyright Burdenoff Consultancy Services Pvt. Ltd.

Support

Metadata

Release files for headshotmarketing-sdk 2026.1107.1

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

Source distribution (sdist)

Source distribution for headshotmarketing-sdk 2026.1107.1
File Size Uploaded Provenance Actions
headshotmarketing_sdk-2026.1107.1.tar.gz 15.5 kB Without provenance Details for headshotmarketing_sdk-2026.1107.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for headshotmarketing-sdk 2026.1107.1
File Interpreter ABI Platform Actions
headshotmarketing_sdk-2026.1107.1-py3-none-any.whl Python 3 none any Details for headshotmarketing_sdk-2026.1107.1-py3-none-any.whl

Total release size: 23.9 kB

Release files / headshotmarketing_sdk-2026.1107.1.tar.gz

Download URL headshotmarketing_sdk-2026.1107.1.tar.gz
Size 15.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b79880af86cf75506af993aa75badedee208c0d9516ec432a52953bd9a71b3c1
BLAKE2b-256 checksum
How to use checksums
b6b7a6abb414969cce19b1976270039aef94a5e0db58e2d16394d3930861b4b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / headshotmarketing_sdk-2026.1107.1-py3-none-any.whl

Download URL headshotmarketing_sdk-2026.1107.1-py3-none-any.whl
Size 8.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce9162efef892c9330af0525381e55360e7bf76f501f80f2fd79e98c8892baf3
BLAKE2b-256 checksum
How to use checksums
90a278d6dc090e068b6d475a5465db23bf857b5f62c05cf99fb40d38540cb263
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.18

Security for headshotmarketing-sdk 2026.1107.1

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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
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