# Dropbox Sign Python SDK

The Dropbox Sign Python SDK provides a comprehensive interface to the Dropbox Sign v3 API (formerly HelloSign), enabling developers to integrate electronic signature and document workflow capabilities into Python applications. This SDK is auto-generated from the official OpenAPI specification, ensuring feature parity with the REST API while providing a Pythonic interface for document signing, template management, embedded signing experiences, and fax capabilities.

Built on Pydantic v2 and supporting Python 3.8+, the SDK handles authentication via API keys or OAuth2 tokens, manages file uploads and downloads, and provides strongly-typed request/response models. All API endpoints are organized into logical API classes (SignatureRequestApi, TemplateApi, AccountApi, etc.), with comprehensive error handling through ApiException and related exception types. The SDK supports both synchronous operations and provides callback verification helpers for webhook event processing.

## API Configuration and Authentication

### Initialize API Client with API Key

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(
    username="YOUR_API_KEY",
)

with ApiClient(configuration) as api_client:
    # Use api_client to call any API endpoint
    account_api = api.AccountApi(api_client)
    response = account_api.account_get()
    print(f"Account: {response.account.email_address}")
```

### Initialize API Client with OAuth Token

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(
    access_token="YOUR_OAUTH_ACCESS_TOKEN",
)

with ApiClient(configuration) as api_client:
    # OAuth-authenticated requests
    signature_api = api.SignatureRequestApi(api_client)
    response = signature_api.signature_request_list()
```

## Signature Request API

### Send a Signature Request

```python
import json
from dropbox_sign import ApiClient, ApiException, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    field_options = models.SubFieldOptions(
        date_format="DD - MM - YYYY",
    )

    signing_options = models.SubSigningOptions(
        default_type="draw",
        draw=True,
        phone=False,
        type=True,
        upload=True,
    )

    signers = [
        models.SubSignatureRequestSigner(
            name="Jack",
            email_address="jack@example.com",
            order=0,
        ),
        models.SubSignatureRequestSigner(
            name="Jill",
            email_address="jill@example.com",
            order=1,
        ),
    ]

    signature_request = models.SignatureRequestSendRequest(
        message="Please sign this NDA and then we can discuss more.",
        subject="The NDA we talked about",
        test_mode=True,
        title="NDA with Acme Co.",
        cc_email_addresses=["lawyer1@dropboxsign.com", "lawyer2@dropboxsign.com"],
        files=[open("./example_signature_request.pdf", "rb").read()],
        metadata={"custom_id": 1234, "custom_text": "NDA #9"},
        field_options=field_options,
        signing_options=signing_options,
        signers=signers,
    )

    try:
        response = api.SignatureRequestApi(api_client).signature_request_send(
            signature_request_send_request=signature_request
        )
        print(f"Signature Request ID: {response.signature_request.signature_request_id}")
        print(f"Status: {response.signature_request.is_complete}")
    except ApiException as e:
        print(f"Exception: {e}")
```

### Get Signature Request Status

```python
from dropbox_sign import ApiClient, ApiException, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    try:
        response = api.SignatureRequestApi(api_client).signature_request_get(
            signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967"
        )

        print(f"Subject: {response.signature_request.subject}")
        print(f"Complete: {response.signature_request.is_complete}")
        print(f"Signatures:")
        for sig in response.signature_request.signatures:
            print(f"  - {sig.signer_name} ({sig.signer_email_address}): {sig.status_code}")
    except ApiException as e:
        print(f"Exception: {e}")
```

### List Signature Requests

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.SignatureRequestApi(api_client).signature_request_list(
        page=1,
        page_size=20
    )

    print(f"Total requests: {response.list_info.num_results}")
    for request in response.signature_requests:
        print(f"{request.signature_request_id}: {request.title} - {request.is_complete}")
```

### Download Signed Files

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.SignatureRequestApi(api_client).signature_request_files(
        signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967",
        file_type="pdf"
    )

    # response is FileResponse containing binary PDF data
    with open("signed_document.pdf", "wb") as f:
        f.write(response)
    print("Downloaded signed document")
```

### Cancel Signature Request

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.SignatureRequestApi(api_client).signature_request_cancel(
        signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967"
    )
    print("Signature request cancelled")
```

### Send Reminder

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    remind_request = models.SignatureRequestRemindRequest(
        email_address="signer@example.com"
    )

    response = api.SignatureRequestApi(api_client).signature_request_remind(
        signature_request_id="fa5c8a0b0f492d768749333ad6fcc214c111e967",
        signature_request_remind_request=remind_request
    )
    print("Reminder sent")
```

## Template API

### Create Template

```python
from dropbox_sign import ApiClient, ApiException, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    signer_roles = [
        models.SubTemplateRole(name="Client", order=0),
        models.SubTemplateRole(name="Witness", order=1),
    ]

    form_fields = [
        models.SubFormFieldsPerDocumentText(
            document_index=0,
            api_id="uniqueIdHere_1",
            type="text",
            required=True,
            signer="1",
            width=100,
            height=16,
            x=112,
            y=328,
            page=1,
            validation_type="numbers_only",
        ),
        models.SubFormFieldsPerDocumentSignature(
            document_index=0,
            api_id="uniqueIdHere_2",
            type="signature",
            required=True,
            signer="0",
            width=120,
            height=30,
            x=530,
            y=415,
            page=1,
        ),
    ]

    merge_fields = [
        models.SubMergeField(name="Full Name", type="text"),
        models.SubMergeField(name="Is Registered?", type="checkbox"),
    ]

    template_request = models.TemplateCreateRequest(
        client_id="37dee8d8440c66d54cfa05d92c160882",
        message="For your approval",
        subject="Please sign this document",
        test_mode=True,
        title="Test Template",
        cc_roles=["Manager"],
        files=[open("./example_signature_request.pdf", "rb").read()],
        signer_roles=signer_roles,
        form_fields_per_document=form_fields,
        merge_fields=merge_fields,
    )

    try:
        response = api.TemplateApi(api_client).template_create(
            template_create_request=template_request
        )
        print(f"Template ID: {response.template.template_id}")
        print(f"Title: {response.template.title}")
    except ApiException as e:
        print(f"Exception: {e}")
```

### Send Signature Request with Template

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    signers = [
        models.SubSignatureRequestTemplateSigner(
            role="Client",
            name="George",
            email_address="george@example.com",
        ),
        models.SubSignatureRequestTemplateSigner(
            role="Witness",
            name="William",
            email_address="william@example.com",
        ),
    ]

    request = models.SignatureRequestSendWithTemplateRequest(
        template_ids=["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
        subject="Purchase Order",
        message="Glad we could come to an agreement.",
        signers=signers,
        test_mode=True,
    )

    response = api.SignatureRequestApi(api_client).signature_request_send_with_template(
        signature_request_send_with_template_request=request
    )
    print(f"Signature Request ID: {response.signature_request.signature_request_id}")
```

### List Templates

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.TemplateApi(api_client).template_list(
        page=1,
        page_size=20
    )

    print(f"Total templates: {response.list_info.num_results}")
    for template in response.templates:
        print(f"{template.template_id}: {template.title}")
```

### Get Template Details

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.TemplateApi(api_client).template_get(
        template_id="c26b8a16784a872da37ea946b9ddec7c1e11dff6"
    )

    print(f"Template: {response.template.title}")
    print(f"Signer roles: {[role.name for role in response.template.signer_roles]}")
    print(f"Documents: {len(response.template.documents)}")
```

### Delete Template

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    api.TemplateApi(api_client).template_delete(
        template_id="c26b8a16784a872da37ea946b9ddec7c1e11dff6"
    )
    print("Template deleted")
```

## Embedded Signing API

### Create Embedded Signature Request

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    signers = [
        models.SubSignatureRequestSigner(
            name="Jack",
            email_address="jack@example.com",
            order=0,
        ),
    ]

    request = models.SignatureRequestCreateEmbeddedRequest(
        client_id="ec64a202072370a737edf4a0eb7f4437",
        title="NDA with Acme Co.",
        subject="The NDA we talked about",
        message="Please sign this NDA",
        signers=signers,
        files=[open("./example_signature_request.pdf", "rb").read()],
        test_mode=True,
    )

    response = api.SignatureRequestApi(api_client).signature_request_create_embedded(
        signature_request_create_embedded_request=request
    )

    signature_id = response.signature_request.signatures[0].signature_id
    print(f"Signature ID: {signature_id}")
```

### Get Embedded Sign URL

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.EmbeddedApi(api_client).embedded_sign_url(
        signature_id="50e3542f738adfa7ddd4cbd4c00d2a8ab6e4194b"
    )

    print(f"Sign URL: {response.embedded.sign_url}")
    print(f"Expires at: {response.embedded.expires_at}")
    # Embed this URL in your application's iframe
```

### Get Embedded Template Edit URL

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    request = models.EmbeddedEditUrlRequest(
        cc_roles=["Manager"],
        merge_fields=[],
    )

    response = api.EmbeddedApi(api_client).embedded_edit_url(
        template_id="5de8179668f2033afac48da1868d0093bf133266",
        embedded_edit_url_request=request
    )

    print(f"Edit URL: {response.embedded.edit_url}")
    print(f"Expires at: {response.embedded.expires_at}")
```

## OAuth API

### Generate OAuth Token

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration()

with ApiClient(configuration) as api_client:
    token_request = models.OAuthTokenGenerateRequest(
        client_id="cc91c61d00f8bb2ece1428035716b",
        client_secret="1d14434088507ffa390e6f5528465",
        code="1b0d28d90c86c141",
        state="900e06e2",
        grant_type="authorization_code",
    )

    try:
        response = api.OAuthApi(api_client).oauth_token_generate(
            o_auth_token_generate_request=token_request
        )

        print(f"Access Token: {response.access_token}")
        print(f"Refresh Token: {response.refresh_token}")
        print(f"Token Type: {response.token_type}")
        print(f"Expires In: {response.expires_in}")
    except ApiException as e:
        print(f"Exception: {e}")
```

### Refresh OAuth Token

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration()

with ApiClient(configuration) as api_client:
    refresh_request = models.OAuthTokenRefreshRequest(
        refresh_token="hNTI2MTFmM2VmZDQxZTZjOWRmZmFjZmVmMGMyNGFjMzI2MGI5YzgzNmE3",
        grant_type="refresh_token",
    )

    response = api.OAuthApi(api_client).oauth_token_refresh(
        o_auth_token_refresh_request=refresh_request
    )

    print(f"New Access Token: {response.access_token}")
    print(f"Expires In: {response.expires_in}")
```

## Account API

### Create Account

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    account_request = models.AccountCreateRequest(
        email_address="newuser@dropboxsign.com",
    )

    try:
        response = api.AccountApi(api_client).account_create(
            account_create_request=account_request
        )
        print(f"Account ID: {response.account.account_id}")
        print(f"Email: {response.account.email_address}")
    except ApiException as e:
        print(f"Exception: {e}")
```

### Get Account Information

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.AccountApi(api_client).account_get()

    account = response.account
    print(f"Account ID: {account.account_id}")
    print(f"Email: {account.email_address}")
    print(f"Is Locked: {account.is_locked}")
    print(f"Is Paid HS: {account.is_paid_hs}")
    print(f"Quotas: {account.quotas}")
```

### Update Account

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    update_request = models.AccountUpdateRequest(
        callback_url="https://www.example.com/callback",
    )

    response = api.AccountApi(api_client).account_update(
        account_update_request=update_request
    )
    print(f"Updated callback URL: {response.account.callback_url}")
```

## Fax API

### Send Fax

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    fax_request = models.FaxSendRequest(
        recipient="16690000001",
        sender="16690000000",
        test_mode=True,
        cover_page_to="Jill Fax",
        cover_page_from="Faxer Faxerson",
        cover_page_message="I'm sending you a fax!",
        title="This is what the fax is about!",
        files=[open("./example_fax.pdf", "rb").read()],
    )

    try:
        response = api.FaxApi(api_client).fax_send(fax_send_request=fax_request)
        print(f"Fax ID: {response.fax.fax_id}")
        print(f"Status: {response.fax.status}")
    except ApiException as e:
        print(f"Exception: {e}")
```

### Get Fax Details

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.FaxApi(api_client).fax_get(
        fax_id="fa5c8a0b0f492d768749333ad6fcc214c111e967"
    )

    print(f"Fax ID: {response.fax.fax_id}")
    print(f"From: {response.fax.from_phone_number}")
    print(f"To: {response.fax.to_phone_number}")
    print(f"Status: {response.fax.status}")
```

### List Faxes

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.FaxApi(api_client).fax_list(
        page=1,
        page_size=20
    )

    print(f"Total faxes: {response.list_info.num_results}")
    for fax in response.faxes:
        print(f"{fax.fax_id}: {fax.title} - {fax.status}")
```

## Bulk Send API

### Bulk Send with Template

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    signer_list = [
        models.SubBulkSignerList(
            signers=[
                models.SubSignatureRequestTemplateSigner(
                    role="Client",
                    name="George",
                    email_address="george@example.com",
                ),
            ],
            custom_fields=[
                models.SubBulkSignerListCustomField(
                    name="company",
                    value="ABC Corp",
                ),
            ],
        ),
        models.SubBulkSignerList(
            signers=[
                models.SubSignatureRequestTemplateSigner(
                    role="Client",
                    name="Mary",
                    email_address="mary@example.com",
                ),
            ],
            custom_fields=[
                models.SubBulkSignerListCustomField(
                    name="company",
                    value="XYZ Inc",
                ),
            ],
        ),
    ]

    request = models.SignatureRequestBulkSendWithTemplateRequest(
        template_ids=["c26b8a16784a872da37ea946b9ddec7c1e11dff6"],
        subject="Purchase Order",
        message="Glad we could come to an agreement.",
        signer_list=signer_list,
        test_mode=True,
    )

    response = api.SignatureRequestApi(api_client).signature_request_bulk_send_with_template(
        signature_request_bulk_send_with_template_request=request
    )
    print(f"Bulk Send Job ID: {response.bulk_send_job.bulk_send_job_id}")
```

### Get Bulk Send Job

```python
from dropbox_sign import ApiClient, Configuration, api

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    response = api.BulkSendJobApi(api_client).bulk_send_job_get(
        bulk_send_job_id="6e683bc0369ba3d5b6f43c2c22a8031dbf6bd174"
    )

    print(f"Job ID: {response.bulk_send_job.bulk_send_job_id}")
    print(f"Total: {response.bulk_send_job.total}")
    print(f"Is Complete: {response.bulk_send_job.is_complete}")
```

## Event Callback Processing

### Verify and Process Webhook Events

```python
from dropbox_sign import EventCallbackHelper
from dropbox_sign.models import EventCallbackRequest

api_key = "324e3b0840f065eb51f3fd63231d0d33daa35d4ed10d27718839e81737065782"

# Callback data from POST request
callback_data = {
    "event": {
        "event_type": "signature_request_signed",
        "event_time": "1669926463",
        "event_hash": "ff8b03439122f9160500c3fb855bdee5a9ccba5fff27d3b258745d8f3074832f",
        "event_metadata": {
            "related_signature_id": "5de8179668f2033afac48da1868d0093bf133266",
            "reported_for_account_id": "6421d70b9bd45059fa207d03ab8d1b96515b472c",
            "reported_for_app_id": None,
            "event_message": None,
        },
    },
}

callback_event = EventCallbackRequest.init(callback_data)

# Verify authenticity
if EventCallbackHelper.is_valid(api_key, callback_event):
    event_type = callback_event.event.event_type
    signature_id = callback_event.event.event_metadata.related_signature_id

    print(f"Valid event: {event_type}")
    print(f"Signature ID: {signature_id}")

    # Process based on event type
    if event_type == "signature_request_signed":
        print("Document was signed!")
    elif event_type == "signature_request_sent":
        print("Document was sent for signature")
    elif event_type == "signature_request_all_signed":
        print("All parties have signed!")
else:
    print("Invalid callback - possible forgery attempt")
```

## Team API

### Create Team

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    team_request = models.TeamCreateRequest(
        name="New Team Name",
    )

    response = api.TeamApi(api_client).team_create(team_create_request=team_request)
    print(f"Team ID: {response.team.team_id}")
    print(f"Team Name: {response.team.name}")
```

### Add Team Member

```python
from dropbox_sign import ApiClient, Configuration, api, models

configuration = Configuration(username="YOUR_API_KEY")

with ApiClient(configuration) as api_client:
    add_member_request = models.TeamAddMemberRequest(
        email_address="newmember@example.com",
        role="Member",
    )

    response = api.TeamApi(api_client).team_add_member(
        team_add_member_request=add_member_request
    )
    print(f"Member added to team")
```

## Summary

The Dropbox Sign Python SDK provides a complete toolkit for integrating electronic signature workflows into Python applications. Core use cases include sending documents for signature (both simple requests and template-based workflows), managing reusable templates with form fields and merge fields, creating embedded signing experiences within your application using iframes, and processing real-time webhook events to track document status changes. The SDK also supports bulk sending for high-volume operations, fax capabilities, team management, and OAuth-based authentication for multi-tenant applications.

Integration patterns typically involve initializing the ApiClient with configuration credentials, using strongly-typed request models to construct API calls, and handling responses through Pydantic-validated response objects. Error handling uses ApiException for API errors, with test_mode available on most endpoints for development and testing. The SDK's auto-generated nature ensures it stays synchronized with API updates, while EventCallbackHelper provides cryptographic verification of webhook payloads for secure event processing. File handling is straightforward using binary file reads, and all responses include comprehensive metadata for tracking signatures, managing document lifecycles, and auditing workflows.