Dropbox Sign (HelloSign) Account API
{'$ref': './markdown/en/tags/account-tag-description.md'}
{'$ref': './markdown/en/tags/account-tag-description.md'}
openapi: 3.0.3
info:
title: Dropbox Sign Account API
description: Dropbox Sign v3 API
termsOfService: https://www.hellosign.com/terms
contact:
email: apisupport@hellosign.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
version: 3.0.0
servers:
- url: https://api.hellosign.com/v3
security:
- api_key: []
- oauth2:
- account_access
- signature_request_access
- template_access
- team_access
- api_app_access
- basic_account_info
- request_signature
tags:
- name: Account
description:
$ref: ./markdown/en/tags/account-tag-description.md
paths:
/account/create:
post:
tags:
- Account
summary: Create Account
description: Creates a new Dropbox Sign Account that is associated with the specified `email_address`.
operationId: accountCreate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreateRequest'
examples:
example:
$ref: '#/components/examples/AccountCreateRequest'
oauth_example:
$ref: '#/components/examples/AccountCreateRequestOAuth'
responses:
'200':
description: successful operation
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/X-Ratelimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCreateResponse'
examples:
example:
$ref: '#/components/examples/AccountCreateResponse'
oauth_example:
$ref: '#/components/examples/AccountCreateOAuthResponse'
4XX:
description: failed_operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
400_example:
$ref: '#/components/examples/Error400Response'
401_example:
$ref: '#/components/examples/Error401Response'
402_example:
$ref: '#/components/examples/Error402Response'
403_example:
$ref: '#/components/examples/Error403Response'
429_example:
$ref: '#/components/examples/Error429Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- account_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/AccountCreateExample.php
- lang: C#
label: C#
source:
$ref: examples/AccountCreateExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/AccountCreateExample.ts
- lang: Java
label: Java
source:
$ref: examples/AccountCreateExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/AccountCreateExample.rb
- lang: Python
label: Python
source:
$ref: examples/AccountCreateExample.py
- lang: cURL
label: cURL
source:
$ref: examples/AccountCreateExample.sh
x-meta:
seo:
title: Create Account | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build with a range of tools. Find out how to create a new Dropbox Sign Account using the specified `email_address` here.
/account:
get:
tags:
- Account
summary: Get Account
description: Returns the properties and settings of your Account.
operationId: accountGet
parameters:
- name: account_id
in: query
description: '`account_id` or `email_address` is required. If both are provided, the account id prevails.
The ID of the Account.'
required: false
schema:
type: string
- name: email_address
in: query
description: '`account_id` or `email_address` is required, If both are provided, the account id prevails.
The email address of the Account.'
required: false
schema:
type: string
responses:
'200':
description: successful operation
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/X-Ratelimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountGetResponse'
examples:
example:
$ref: '#/components/examples/AccountGetResponse'
4XX:
description: failed_operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
400_example:
$ref: '#/components/examples/Error400Response'
401_example:
$ref: '#/components/examples/Error401Response'
402_example:
$ref: '#/components/examples/Error402Response'
403_example:
$ref: '#/components/examples/Error403Response'
429_example:
$ref: '#/components/examples/Error429Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- account_access
- basic_account_info
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/AccountGetExample.php
- lang: C#
label: C#
source:
$ref: examples/AccountGetExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/AccountGetExample.ts
- lang: Java
label: Java
source:
$ref: examples/AccountGetExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/AccountGetExample.rb
- lang: Python
label: Python
source:
$ref: examples/AccountGetExample.py
- lang: cURL
label: cURL
source:
$ref: examples/AccountGetExample.sh
x-meta:
seo:
title: Get Account | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build with a wide range of tools. To find out how to return the properties and settings of your Account, click here.
put:
tags:
- Account
summary: Update Account
description: Updates the properties and settings of your Account. Currently only allows for updates to the [Callback URL](/api/reference/tag/Callbacks-and-Events) and locale.
operationId: accountUpdate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountUpdateRequest'
examples:
example:
$ref: '#/components/examples/AccountUpdateRequest'
responses:
'200':
description: successful operation
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/X-Ratelimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountGetResponse'
examples:
example:
$ref: '#/components/examples/AccountUpdateResponse'
4XX:
description: failed_operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
400_example:
$ref: '#/components/examples/Error400Response'
401_example:
$ref: '#/components/examples/Error401Response'
402_example:
$ref: '#/components/examples/Error402Response'
403_example:
$ref: '#/components/examples/Error403Response'
429_example:
$ref: '#/components/examples/Error429Response'
409_example:
$ref: '#/components/examples/Error409Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- account_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/AccountUpdateExample.php
- lang: C#
label: C#
source:
$ref: examples/AccountUpdateExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/AccountUpdateExample.ts
- lang: Java
label: Java
source:
$ref: examples/AccountUpdateExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/AccountUpdateExample.rb
- lang: Python
label: Python
source:
$ref: examples/AccountUpdateExample.py
- lang: cURL
label: cURL
source:
$ref: examples/AccountUpdateExample.sh
x-meta:
seo:
title: Update Account | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build with a wide range of tools. To find out how update the properties and settings of your Account, click here.
/account/verify:
post:
tags:
- Account
summary: Verify Account
description: Verifies whether an Dropbox Sign Account exists for the given email address.
operationId: accountVerify
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountVerifyRequest'
examples:
example:
$ref: '#/components/examples/AccountVerifyRequest'
responses:
'200':
description: successful operation
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-Ratelimit-Reset:
$ref: '#/components/headers/X-Ratelimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/AccountVerifyResponse'
examples:
example:
$ref: '#/components/examples/AccountVerifyFoundResponse'
not_found_example:
$ref: '#/components/examples/AccountVerifyNotFoundResponse'
4XX:
description: failed_operation
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
400_example:
$ref: '#/components/examples/Error400Response'
401_example:
$ref: '#/components/examples/Error401Response'
402_example:
$ref: '#/components/examples/Error402Response'
403_example:
$ref: '#/components/examples/Error403Response'
429_example:
$ref: '#/components/examples/Error429Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- account_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/AccountVerifyExample.php
- lang: C#
label: C#
source:
$ref: examples/AccountVerifyExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/AccountVerifyExample.ts
- lang: Java
label: Java
source:
$ref: examples/AccountVerifyExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/AccountVerifyExample.rb
- lang: Python
label: Python
source:
$ref: examples/AccountVerifyExample.py
- lang: cURL
label: cURL
source:
$ref: examples/AccountVerifyExample.sh
x-meta:
seo:
title: Verify Account | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build with a wide range of tools. To find out how to verify whether an Account exists, click here.
components:
examples:
AccountVerifyNotFoundResponse:
summary: Account Not Found
value:
$ref: examples/json/AccountVerifyNotFoundResponse.json
AccountGetResponse:
summary: Account Get
value:
$ref: examples/json/AccountGetResponse.json
AccountVerifyRequest:
summary: Default Example
value:
$ref: examples/json/AccountVerifyRequest.json
AccountUpdateResponse:
summary: Account Update
value:
$ref: examples/json/AccountUpdateResponse.json
Error401Response:
summary: Error 401 unauthorized
value:
$ref: examples/json/Error401Response.json
AccountUpdateRequest:
summary: Default Example
value:
$ref: examples/json/AccountUpdateRequest.json
Error409Response:
summary: Error 409 conflict
value:
$ref: examples/json/Error409Response.json
Error400Response:
summary: Error 400 bad_request
value:
$ref: examples/json/Error400Response.json
Error402Response:
summary: Error 402 payment_required
value:
$ref: examples/json/Error402Response.json
Error4XXResponse:
summary: Error 4XX failed_operation
value:
$ref: examples/json/Error4XXResponse.json
AccountCreateRequest:
summary: Default Example
value:
$ref: examples/json/AccountCreateRequest.json
AccountCreateResponse:
summary: Account Create
value:
$ref: examples/json/AccountCreateResponse.json
Error403Response:
summary: Error 403 forbidden
value:
$ref: examples/json/Error403Response.json
AccountVerifyFoundResponse:
summary: Account Found
value:
$ref: examples/json/AccountVerifyFoundResponse.json
AccountCreateOAuthResponse:
summary: Account Create with OAuth Authorization
value:
$ref: examples/json/AccountCreateOAuthResponse.json
Error429Response:
summary: Error 429 exceeded_rate
value:
$ref: examples/json/Error429Response.json
AccountCreateRequestOAuth:
summary: OAuth Example
value:
$ref: examples/json/AccountCreateRequestOAuth.json
schemas:
AccountVerifyRequest:
required:
- email_address
properties:
email_address:
description: Email address to run the verification for.
type: string
format: email
type: object
AccountVerifyResponseAccount:
properties:
email_address:
description: The email address associated with the Account.
type: string
type: object
x-internal-class: true
AccountResponseUsage:
description: Details concerning monthly usage
properties:
fax_pages_sent:
description: Number of fax pages sent
type: integer
nullable: true
type: object
x-internal-class: true
AccountCreateRequest:
required:
- email_address
properties:
client_id:
description: 'Used when creating a new account with OAuth authorization.
See [OAuth 2.0 Authorization](https://app.hellosign.com/api/oauthWalkthrough#OAuthAuthorization)'
type: string
client_secret:
description: 'Used when creating a new account with OAuth authorization.
See [OAuth 2.0 Authorization](https://app.hellosign.com/api/oauthWalkthrough#OAuthAuthorization)'
type: string
email_address:
description: The email address which will be associated with the new Account.
type: string
format: email
locale:
description: The locale used in this Account. Check out the list of [supported locales](/api/reference/constants/#supported-locales) to learn more about the possible values.
type: string
type: object
AccountResponse:
properties:
account_id:
description: The ID of the Account
type: string
email_address:
description: The email address associated with the Account.
type: string
is_locked:
description: Returns `true` if the user has been locked out of their account by a team admin.
type: boolean
is_paid_hs:
description: Returns `true` if the user has a paid Dropbox Sign account.
type: boolean
is_paid_hf:
description: Returns `true` if the user has a paid HelloFax account.
type: boolean
quotas:
$ref: '#/components/schemas/AccountResponseQuotas'
callback_url:
description: The URL that Dropbox Sign events will `POST` to.
type: string
nullable: true
role_code:
description: The membership role for the team.
type: string
nullable: true
team_id:
description: The id of the team account belongs to.
type: string
nullable: true
locale:
description: The locale used in this Account. Check out the list of [supported locales](/api/reference/constants/#supported-locales) to learn more about the possible values.
type: string
nullable: true
usage:
$ref: '#/components/schemas/AccountResponseUsage'
settings:
$ref: '#/components/schemas/AccountResponseSettings'
type: object
x-internal-class: true
ErrorResponseError:
description: Contains information about an error that occurred.
required:
- error_msg
- error_name
properties:
error_msg:
description: Message describing an error.
type: string
error_path:
description: Path at which an error occurred.
type: string
error_name:
description: Name of the error. See the `x-error-codes` catalog in openapi file for a complete list of possible error codes with detailed information including HTTP status codes, causes, remediation steps, and retry guidance.
type: string
type: object
AccountGetResponse:
required:
- account
properties:
account:
$ref: '#/components/schemas/AccountResponse'
warnings:
description: A list of warnings.
type: array
items:
$ref: '#/components/schemas/WarningResponse'
type: object
x-internal-class: true
AccountResponseQuotas:
description: Details concerning remaining monthly quotas.
properties:
api_signature_requests_left:
description: API signature requests remaining.
type: integer
nullable: true
documents_left:
description: Signature requests remaining.
type: integer
nullable: true
templates_total:
description: Total API templates allowed.
type: integer
nullable: true
templates_left:
description: API templates remaining.
type: integer
nullable: true
sms_verifications_left:
description: SMS verifications remaining.
type: integer
nullable: true
num_fax_pages_left:
description: Number of fax pages left
type: integer
nullable: true
type: object
x-internal-class: true
AccountResponseSettings:
description: Subset of configured settings
properties:
signer_access_codes:
description: Returns `true` if _Custom access codes_ is enabled in Admin Console. [Read more](https://developers.hellosign.com/docs/sms-tools/walkthrough).
type: boolean
sms_delivery:
description: Returns `true` if _Text message_ is enabled in Admin Console. [Read more](https://developers.hellosign.com/docs/sms-tools/walkthrough).
type: boolean
sms_authentication:
description: Returns `true` if _Signer authentication_ is enabled in Admin Console. [Read more](https://developers.hellosign.com/docs/sms-tools/walkthrough).
type: boolean
type: object
x-internal-class: true
ErrorResponse:
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorResponseError'
type: object
OAuthTokenResponse:
properties:
access_token:
type: string
token_type:
type: string
refresh_token:
type: string
expires_in:
description: Number of seconds until the `access_token` expires. Uses epoch time.
type: integer
state:
type: string
nullable: true
type: object
x-internal-class: true
AccountCreateResponse:
required:
- account
properties:
account:
$ref: '#/components/schemas/AccountResponse'
oauth_data:
$ref: '#/components/schemas/OAuthTokenResponse'
warnings:
description: A list of warnings.
type: array
items:
$ref: '#/components/schemas/WarningResponse'
type: object
x-internal-class: true
WarningResponse:
description: A list of warnings.
required:
- warning_msg
- warning_name
properties:
warning_msg:
description: Warning message
type: string
warning_name:
description: Warning name
type: string
type: object
AccountUpdateRequest:
properties:
account_id:
description: The ID of the Account
type: string
nullable: true
callback_url:
description: The URL that Dropbox Sign should POST events to.
type: string
locale:
description: The locale used in this Account. Check out the list of [supported locales](/api/reference/constants/#supported-locales) to learn more about the possible values.
type: string
type: object
AccountVerifyResponse:
properties:
account:
$ref: '#/components/schemas/AccountVerifyResponseAccount'
warnings:
description: A list of warnings.
type: array
items:
$ref: '#/components/schemas/WarningResponse'
type: object
x-internal-class: true
headers:
X-Ratelimit-Reset:
description: The Unix time at which the rate limit will reset to its maximum.
schema:
type: integer
format: int64
example: 1430170900
X-RateLimit-Remaining:
description: The number of requests remaining in the current rate limit window.
schema:
type: integer
format: int32
example: 99
X-RateLimit-Limit:
description: The maximum number of requests per hour that you can make.
schema:
type: integer
format: int32
example: 100
securitySchemes:
api_key:
type: http
description: 'Your API key can be used to make calls to the Dropbox Sign API. See [Authentication](/api/reference/authentication) for more information.
✅ Supported by Try it console (calls sent in `test_mode` only).'
scheme: basic
oauth2:
type: http
description: 'You can use an Access Token issued through an OAuth flow to send calls to the Dropbox Sign API from your app. The access scopes required by this endpoint are listed in the gray box above. See [Authentication](/api/reference/authentication) for more information.
❌ **Not supported** by Try it console.'
bearerFormat: JWT
scheme: bearer
externalDocs:
description: Legacy API Reference
url: https://app.hellosign.com/api/reference
x-webhooks:
accountCallback:
post:
summary: Account Callbacks
operationId: accountUpdateEventCallback
description:
$ref: ./markdown/en/descriptions/account-callback-description.md
tags:
- Callbacks and Events
x-meta:
seo:
title: Account Callbacks | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build with a wide range of tools. To find out how to consume Dropbox Sign Events at the account level, click here.
x-fern-audiences:
- events
requestBody:
description: "**Account Callback Payloads --**\n Events that are reported at the Account level through the the *Account callback URL* defined in your [API settings](https://app.hellosign.com/home/myAccount#api). The *Account callback URL* can also be updated by calling [Update Account](/api/reference/operation/accountUpdate) and passing a `callback_url`."
content:
application/json:
schema:
$ref: '#/components/schemas/EventCallbackPayload'
examples:
signature_request_viewed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestViewed'
signature_request_signed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestSigned'
signature_request_signer_removed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestSignerRemoved'
signature_request_downloadable_example:
$ref: '#/components/examples/EventCallbackSignatureRequestDownloadable'
signature_request_sent_example:
$ref: '#/components/examples/EventCallbackSignatureRequestSent'
signature_request_all_signed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestAllSigned'
signature_request_invalid_example:
$ref: '#/components/examples/EventCallbackSignatureRequestInvalid'
signature_request_email_bounce_example:
$ref: '#/components/examples/EventCallbackSignatureRequestEmailBounce'
signature_request_remind_example:
$ref: '#/components/examples/EventCallbackSignatureRequestRemind'
signature_request_incomplete_qes_example:
$ref: '#/components/examples/EventCallbackSignatureRequestIncompleteQes'
signature_request_destroyed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestDestroyed'
signature_request_canceled_example:
$ref: '#/components/examples/EventCallbackSignatureRequestCanceled'
signature_request_declined_example:
$ref: '#/components/examples/EventCallbackSignatureRequestDeclined'
signature_request_expired_example:
$ref: '#/components/examples/EventCallbackSignatureRequestExpired'
signature_request_reassigned_example:
$ref: '#/components/examples/EventCallbackSignatureRequestReassigned'
signature_request_prepared_example:
$ref: '#/components/examples/EventCallbackSignatureRequestPrepared'
account_confirmed_example:
$ref: '#/components/examples/EventCallbackAccountConfirmed'
unknown_error_example:
$ref: '#/components/examples/EventCallbackUnknownError'
file_error_example:
$ref: '#/components/examples/EventCallbackFileError'
template_created_example:
$ref: '#/components/examples/EventCallbackTemplateCreated'
template_error_example:
$ref: '#/components/examples/EventCallbackTemplateError'
sign_url_invalid_example:
$ref: '#/components/examples/EventCallbackSignUrlInvalid'
callback_test_example:
$ref: '#/components/examples/EventCallbackCallbackTest'
responses:
200:
$ref: '#/components/responses/EventCallbackResponse'
appCallback:
post:
summary: App Callbacks
operationId: apiAppCreateEventCallback
description:
$ref: ./markdown/en/descriptions/api-app-callback-description.md
tags:
- Callbacks and Events
x-meta:
seo:
title: App Callbacks | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build with a wide range of tools. To find out how to consume Dropbox Sign Events at the App level, click here.
x-fern-audiences:
- events
requestBody:
description: '**API App Callback Payloads --**
Events that are reported at the API App level through the *Event callback URL* defined in your [API settings](https://app.hellosign.com/home/myAccount#api) for a specific app. The *Event callback URL* can also be updated by calling [Update API App](/api/reference/operation/apiAppUpdate) and passing a `callback_url`.'
content:
application/json:
schema:
$ref: '#/components/schemas/EventCallbackPayload'
examples:
signature_request_viewed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestViewed'
signature_request_signed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestSigned'
signature_request_signer_removed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestSignerRemoved'
signature_request_downloadable_example:
$ref: '#/components/examples/EventCallbackSignatureRequestDownloadable'
signature_request_sent_example:
$ref: '#/components/examples/EventCallbackSignatureRequestSent'
signature_request_all_signed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestAllSigned'
signature_request_invalid_example:
$ref: '#/components/examples/EventCallbackSignatureRequestInvalid'
signature_request_email_bounce_example:
$ref: '#/components/examples/EventCallbackSignatureRequestEmailBounce'
signature_request_remind_example:
$ref: '#/components/examples/EventCallbackSignatureRequestRemind'
signature_request_incomplete_qes_example:
$ref: '#/components/examples/EventCallbackSignatureRequestIncompleteQes'
signature_request_destroyed_example:
$ref: '#/components/examples/EventCallbackSignatureRequestDestroyed'
signature_request_canceled_example:
$ref: '#/components/examples/EventCallbackSignatureRequestCanceled'
signature_request_declined_example:
$ref: '#/components/examples/EventCallbackSignatureRequestDeclined'
signature_request_expired_example:
$ref: '#/components/examples/EventCallbackSignatureRequestExpired'
signature_request_reassigned_example:
$ref: '#/components/examples/EventCallbackSignatureRequestReassigned'
signature_request_prepared_example:
$ref: '#/components/examples/EventCallbackSignatureRequestPrepared'
account_confirmed_example:
$ref: '#/components/examples/EventCallbackAccountConfirmed'
unknown_error_example:
$ref: '#/components/ex
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hellosign/refs/heads/main/openapi/hellosign-account-api-openapi.yml