Demandbase SDK Documentation

Overview

This SDK provides a Python client for interacting with Demandbase APIs, including B2B search, data import, and data export endpoints.

• What the SDK does: Wraps Demandbase REST APIs into a typed Python client and Pydantic models for easy integration.
• Who should use it: External developers building Python integrations with Demandbase services.
• Supported use cases: Company/contact search, bulk matching, export job creation/monitoring, import job submission, administrative APIs.
• Supported runtimes: Python 3.8+

Installation

Install from PyPI:

pip install demandbase-sdk

Runtime requirements:

• Python >= 3.8

Environment variables:

• DEMANDBASE_CLIENT_ID (required)
• DEMANDBASE_CLIENT_SECRET (required)

Authentication prerequisites:

• A Demandbase client ID and client secret with API access.

Quick Start

Initialize the Client

import demandbase

# Export credentials in your environment first
# export DEMANDBASE_CLIENT_ID=YOUR_ID
# export DEMANDBASE_CLIENT_SECRET=YOUR_SECRET

with demandbase.DBClient(timeout=60.0, retry_count=2) as client:
    try:
        # Example: list subscriptions (B2B API)
        subs = client.b2b_api.list_subscriptions(page=1, per_page=10)
        print(subs)
    except demandbase.DemandBaseAPIError as error:
        print(f"Demandbase API error: {error.http_status_code} - {error.error_message}")

The SDK returns a Pydantic SubscriptionList model, not a raw dict. You can access fields directly or serialize the model when you need JSON:

print(subs.subscriptions)
print(subs.model_dump())

Example serialized shape:

{
    "subscriptions": [
        {
            "subscriptionId": "SUBSCRIPTION_ID",
            "name": "Example subscription",
            "description": "Example subscription description",
            "subscriptionType": "company",
            "frequency": "daily",
            "fields": ["companyId", "name"],
            "createdAt": "2026-01-01T00:00:00Z",
            "nextFireTime": "2026-01-02T00:00:00Z"
        }
    ]
}

Authentication and Configuration

Supported authentication methods

• Client credentials (OAuth2 client_credentials) via DEMANDBASE_CLIENT_ID and DEMANDBASE_CLIENT_SECRET environment variables.

Configuration

• DBClient(timeout=..., retry_count=...) — set request timeout in seconds and retry attempts.
• The SDK manages tokens internally; tokens are cached until near-expiry.
• Logging: enable SDK logging with demandbase.enable_logging().

Logging

SDK logging is disabled by default except for warnings and errors emitted through your application's logging setup. Enable Demandbase SDK logs explicitly when troubleshooting requests, retries, authentication, or response handling.

Enable default warning-level SDK logs:

import demandbase

demandbase.enable_logging()

Enable a specific log level in code:

import demandbase

demandbase.enable_logging("INFO")

By default, SDK logs are written to standard error (stderr). To send logs to a different destination, pass a stream.

Write SDK logs to standard output:

import sys
import demandbase

demandbase.enable_logging("INFO", stream=sys.stdout)

Write SDK logs to a file:

import demandbase

log_file = open("demandbase-sdk.log", "a", encoding="utf-8")
demandbase.enable_logging("DEBUG", stream=log_file)

Or configure logging with an environment variable before your application starts:

export DEMANDBASE_LOG_LEVEL=INFO

Supported levels are DEBUG, INFO, WARNING, and ERROR. Configure logging once near application startup so the SDK uses the intended level and destination. Use DEBUG only during troubleshooting because it can produce verbose request diagnostics. Authorization tokens are redacted from SDK log output.

Security best practices

• Do not commit DEMANDBASE_CLIENT_SECRET to source control.
• Use environment variables or a secret manager.

Module Reference

Top-level package: demandbase.

• DBClient (alias for DemandbaseClient) — main client.
• DemandBaseAPIError — exception type raised for API errors.
• B2B, Export, Import, Admin, Common — namespaces for request models, response models, and enums.
• enable_logging() — helper to configure SDK logging.

See the Python SDK API Reference for detailed API and model documentation.

Data Types

Models are provided as Pydantic models under demandbase.models with subpackages: B2B, Export, Import, Admin, Common.

Common public models:

• demandbase.models.B2B.CompanyRequest / CompanyResponse — company search payloads.
• demandbase.models.Export.Job, ExportJobSearchResults — export job models.
• demandbase.models.Import.ImportJob, ImportJobSubmitResponse — import models.

For field-level details, see the Python SDK API Reference.

Common Workflows

• Initialize SDK: use with demandbase.DBClient() as client or instantiate and call close().
• Make a request: call resource methods like client.b2b_api.search_companies(...) with Pydantic request models.
• Handle errors: catch DemandBaseAPIError.
• Bulk import CSV jobs: use client.data_import_api.submit_import_data(...) with CSV data as a pandas.DataFrame, raw bytes, or a local file path string. When you pass a path string, the SDK opens and reads the file.

Error Handling

See Python SDK Error Handling for error classes, handling patterns, and retries.

Pagination, Rate Limits, and Retries

• Pagination: list methods commonly support a page number and the number of results to return per page.
• Retries: if a request receives a 401 because the access token is invalid or expired, DBClient refreshes the token and retries. It also retries 429/5xx server errors up to retry_count with exponential backoff (initial 30s, doubling up to 600s).
• Rate limits: if the API returns a rate-limit response, the SDK raises DemandBaseAPIError after any configured retries are exhausted. Check the error status and response headers to decide when to retry the request.

Troubleshooting

• Missing credentials: confirm DEMANDBASE_CLIENT_ID and DEMANDBASE_CLIENT_SECRET are set in the environment where your application runs.
• Authentication errors: confirm the client ID and client secret are valid and have access to the Demandbase APIs you are calling.
• Permission errors: confirm your Demandbase account is enabled for the endpoint or data type used by the request.
• Network or timeout errors: check outbound network access from your application, then increase the client timeout, in seconds, if the request normally takes longer to complete.
• Unexpected response data: confirm the request parameters and account permissions match the expected API response. If the issue persists, capture the request context and error details for support.

FAQ

• Q: Is there a sandbox or staging environment for SDK testing?
• A: No. The SDK connects to the production Demandbase API. Use test records, small request sizes, and non-destructive read operations when validating a new integration.
• Q: How do I get API credentials?
• A: A Demandbase administrator can create an API Key Set in Demandbase One and generate a token that provides a client ID and client secret. During setup, select the API permissions your integration needs. If the required API options are not available, contact your Demandbase account team. See Generate and Manage API Key Sets.
• Q: Does the SDK make synchronous requests?
• A: Yes. SDK methods wait for the API response before returning or raising an error.
• Q: How do I install the latest SDK version?
• A: Run pip install demandbase-sdk. Use a pinned version only when your deployment process requires reproducible installs.
• Q: Does the SDK handle token refresh?
• A: Yes. The SDK manages access tokens and retries a request when a token is invalid or expired.
• Q: Where can I find the full list of available methods and models?
• A: See the Python SDK API Reference.

Appendix: Full Public API Index

The main package, demandbase, provides the SDK client, API error type, logging helper, and model/enum namespaces used in request and response objects. API methods are available through the client resource attributes, such as client.b2b_api, client.data_export_api, and client.data_import_api. You can use the package namespace or import public objects directly.

Package namespace style:

import demandbase

with demandbase.DBClient() as client:
    ...

Direct import style:

from demandbase import DBClient, DemandBaseAPIError
from demandbase.models.Common import EntityType
from demandbase.models.B2B.CompanySearch import CompanyRequest

For full method lists and model fields, see the Python SDK API Reference.