HelloSign User Management API Guide

Auth method: HTTP Basic Auth with API key (username=API key, password empty); OAuth 2.0 also supported for acting on behalf of other accounts

Setup steps

1. Log in to HelloSign and navigate to API settings at https://app.hellosign.com/home/myAccount#api.
2. Generate an API key from the API section of your account settings.
3. For Basic Auth: pass the API key as the HTTP Basic Auth username with an empty password.
4. For OAuth 2.0: register an OAuth app in the developer dashboard, obtain client_id and client_secret, redirect users through https://app.hellosign.com/oauth/authorize, exchange the authorization code for an access token at https://app.hellosign.com/oauth/token.
5. Include the Bearer token in the Authorization header for OAuth requests.

Required scopes

Get Account

• Method: GET
• URL: https://api.hellosign.com/v3/account
• Watch out for: Returns the account associated with the authenticated API key only; cannot retrieve arbitrary accounts without OAuth acting on their behalf.

Request example

GET /v3/account HTTP/1.1
Authorization: Basic {base64(api_key:)}

Response example

{
  "account": {
    "account_id": "abc123",
    "email_address": "user@example.com",
    "is_paid_hs": true,
    "quotas": {"api_signature_requests_left": 50}
  }
}

Create Account

• Method: POST
• URL: https://api.hellosign.com/v3/account/create
• Watch out for: Creates a standalone HelloSign account; does not automatically add the user to your team. A separate team add-member call is required.

Request example

POST /v3/account/create HTTP/1.1
Content-Type: application/json

{"email_address": "newuser@example.com",
 "password": "SecurePass1!"}

Response example

{
  "account": {
    "account_id": "xyz789",
    "email_address": "newuser@example.com",
    "is_paid_hs": false
  }
}

Update Account

• Method: PUT
• URL: https://api.hellosign.com/v3/account
• Watch out for: Only updates the authenticated account. Updatable fields are limited (callback_url, locale).

Request example

PUT /v3/account HTTP/1.1
Content-Type: application/json

{"callback_url": "https://example.com/callback"}

Response example

{
  "account": {
    "account_id": "abc123",
    "callback_url": "https://example.com/callback"
  }
}

Verify Account

• Method: POST
• URL: https://api.hellosign.com/v3/account/verify
• Watch out for: Returns account_id if the email is registered; useful for checking existence before provisioning.

Request example

POST /v3/account/verify HTTP/1.1
Content-Type: application/json

{"email_address": "user@example.com"}

Response example

{
  "account": {
    "email_address": "user@example.com",
    "account_id": "abc123"
  }
}

Add Team Member

• Method: PUT
• URL: https://api.hellosign.com/v3/team/add_member
• Watch out for: The user must already have a HelloSign account. If not, create the account first via POST /account/create.

Request example

PUT /v3/team/add_member HTTP/1.1
Content-Type: application/json

{"email_address": "newmember@example.com"}

Response example

{
  "team": {
    "name": "My Team",
    "accounts": [{"account_id": "xyz789", "email_address": "newmember@example.com"}]
  }
}

Remove Team Member

• Method: POST
• URL: https://api.hellosign.com/v3/team/remove_member
• Watch out for: Removes the user from the team but does not delete their HelloSign account.

Request example

POST /v3/team/remove_member HTTP/1.1
Content-Type: application/json

{"email_address": "oldmember@example.com"}

Response example

{
  "team": {
    "name": "My Team",
    "accounts": []
  }
}

Get Team

• Method: GET
• URL: https://api.hellosign.com/v3/team
• Watch out for: Returns all team members; no pagination on the accounts array within the response.

Request example

GET /v3/team HTTP/1.1
Authorization: Basic {base64(api_key:)}

Response example

{
  "team": {
    "name": "My Team",
    "accounts": [
      {"account_id": "abc123", "email_address": "admin@example.com", "role_code": "a"}
    ]
  }
}

List Team Members (paginated)

• Method: GET
• URL: https://api.hellosign.com/v3/team/members/{team_id}
• Watch out for: Available in newer API versions; team_id is required. Older GET /team endpoint returns all members without pagination.

Request example

GET /v3/team/members/team_abc?page=1&page_size=20 HTTP/1.1
Authorization: Basic {base64(api_key:)}

Response example

{
  "list_info": {"page": 1, "page_size": 20, "num_pages": 2, "num_results": 35},
  "team_members": [{"account_id": "abc123", "email_address": "user@example.com"}]
}

• Rate limits: HelloSign enforces rate limits per API key. The official documentation does not publicly disclose exact numeric limits per plan tier. Exceeding limits returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when rate limit is exceeded. Retry-After header is included. Exact per-plan numeric limits are not publicly documented.
• Pagination method: offset
• Default page size: 20
• Max page size: 100
• Pagination pointer: page / page_size

• Webhooks available: Yes
• Webhook notes: HelloSign supports event callbacks (webhooks) via a callback_url set at the account level or per signature request. Events are delivered as HTTP POST requests with a JSON payload.
• Alternative event strategy: Poll GET /signature_request/list for status changes if webhooks are not configured.
• Webhook events: signature_request_sent, signature_request_viewed, signature_request_signed, signature_request_all_signed, signature_request_declined, signature_request_remind, signature_request_canceled, signature_request_invalid, account_confirmed, template_created, file_error

• SCIM available: No
• SCIM version: Not documented
• Plan required: Enterprise
• Endpoint: Not documented

Limitations:

• SCIM is not currently supported by HelloSign (Dropbox Sign).
• Dropbox Business (a separate product) supports SCIM, but Dropbox Sign does not.
• SAML SSO is available on Premium/Enterprise plans but SCIM provisioning is not offered.
• SCIM has been referenced as a future roadmap item but is not available as of the current policy date.

Provisioning a new team member is a two-step operation: first POST /v3/account/create to create the HelloSign account (if it does not already exist - verify with POST /v3/account/verify first), then PUT /v3/team/add_member to attach the account to your team.

Skipping the verify step and attempting to create a duplicate account returns an error. Deprovisioning requires POST /v3/team/remove_member to revoke team access, but this does not delete the underlying HelloSign account; full deprovisioning requires a coordinated IdP-level SSO revocation if SAML SSO is configured.

For role auditing, GET /v3/team returns all members with role_code values ('a' = admin, 'm' = member); for larger teams, use the paginated `GET /v3/team/members/{team_id}?

page=1&page_size=100endpoint and iterate usingnum_pagesfromlist_info- the basic/team` endpoint does not paginate its accounts array and may return truncated results.

Provision a new team member

1. POST /v3/account/verify with email_address to check if the account already exists.
2. If account does not exist, POST /v3/account/create with email_address and password.
3. PUT /v3/team/add_member with email_address to add the user to your team.
4. Optionally set role_code in the add_member request to assign admin or member role.

Watch out for: If the email already has a HelloSign account (step 1 returns account_id), skip creation and go directly to add_member. Attempting to create a duplicate account returns an error.

Deprovision a team member

1. POST /v3/team/remove_member with email_address to remove the user from the team.
2. Note: this does not delete the user's HelloSign account; they retain access to their personal account.
3. If SSO is configured, revoke SSO access via your IdP (e.g., Okta) to prevent login.

Watch out for: There is no API endpoint to delete a HelloSign account. Full deprovisioning requires both API team removal and IdP-level SSO revocation.

List all team members and audit roles

1. GET /v3/team to retrieve the team object including all accounts and their role_codes.
2. For larger teams, use GET /v3/team/members/{team_id}?page=1&page_size=100 and iterate pages using num_pages from list_info.
3. Map role_code values: 'a' = admin, 'm' = member to build an audit report.

Watch out for: The basic GET /v3/team endpoint may not paginate the accounts array; use the paginated /team/members/{team_id} endpoint for teams with many members to avoid truncated results.

The most significant API caveat is the absence of a DELETE account endpoint: accounts can be removed from a team but never deleted via the API, leaving orphaned accounts accessible on the free tier.

Rate limit thresholds are not publicly documented for any plan tier; HTTP 429 responses should be handled with exponential backoff and the Retry-After header. The API base URL and SDK package names are in transition as HelloSign migrates to the Dropbox Sign brand - verify the current base URL against official documentation before deploying.

OAuth 2.0 scope granularity is limited and not well-suited for server-side user management; API key auth is the practical default for backend integrations. No SCIM support means any identity graph synchronization pipeline must be built and maintained against the REST API directly, with no standardized schema or lifecycle event stream.