Dropbox Sign (HelloSign) Api App API
{'$ref': './markdown/en/tags/api-app-tag-description.md'}
OpenAPI Specification
openapi: 3.0.3
info:
title: Dropbox Sign Account Api App 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: Api App
description:
$ref: ./markdown/en/tags/api-app-tag-description.md
paths:
/api_app:
post:
tags:
- Api App
summary: Create API App
description: Creates a new API App.
operationId: apiAppCreate
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiAppCreateRequest'
examples:
example:
$ref: '#/components/examples/ApiAppCreateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ApiAppCreateRequest'
responses:
'201':
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/ApiAppGetResponse'
examples:
example:
$ref: '#/components/examples/ApiAppCreateResponse'
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'
404_example:
$ref: '#/components/examples/Error404Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- api_app_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/ApiAppCreateExample.php
- lang: C#
label: C#
source:
$ref: examples/ApiAppCreateExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/ApiAppCreateExample.ts
- lang: Java
label: Java
source:
$ref: examples/ApiAppCreateExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/ApiAppCreateExample.rb
- lang: Python
label: Python
source:
$ref: examples/ApiAppCreateExample.py
- lang: cURL
label: cURL
source:
$ref: examples/ApiAppCreateExample.sh
x-meta:
seo:
title: Create API App | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build custom integrations with a wide range of tools. To find out how to create a new API App, click here.
/api_app/{client_id}:
get:
tags:
- Api App
summary: Get API App
description: Returns an object with information about an API App.
operationId: apiAppGet
parameters:
- name: client_id
in: path
description: The client id of the API App to retrieve.
required: true
schema:
type: string
example: 0dd3b823a682527788c4e40cb7b6f7e9
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/ApiAppGetResponse'
examples:
example:
$ref: '#/components/examples/ApiAppGetResponse'
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'
404_example:
$ref: '#/components/examples/Error404Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- api_app_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/ApiAppGetExample.php
- lang: C#
label: C#
source:
$ref: examples/ApiAppGetExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/ApiAppGetExample.ts
- lang: Java
label: Java
source:
$ref: examples/ApiAppGetExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/ApiAppGetExample.rb
- lang: Python
label: Python
source:
$ref: examples/ApiAppGetExample.py
- lang: cURL
label: cURL
source:
$ref: examples/ApiAppGetExample.sh
x-meta:
seo:
title: Get API App | 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 an object with information about an API App, click here.
put:
tags:
- Api App
summary: Update API App
description: Updates an existing API App. Can only be invoked for apps you own. Only the fields you provide will be updated. If you wish to clear an existing optional field, provide an empty string.
operationId: apiAppUpdate
parameters:
- name: client_id
in: path
description: The client id of the API App to update.
required: true
schema:
type: string
example: 0dd3b823a682527788c4e40cb7b6f7e9
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ApiAppUpdateRequest'
examples:
example:
$ref: '#/components/examples/ApiAppUpdateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/ApiAppUpdateRequest'
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/ApiAppGetResponse'
examples:
example:
$ref: '#/components/examples/ApiAppUpdateResponse'
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:
- api_app_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/ApiAppUpdateExample.php
- lang: C#
label: C#
source:
$ref: examples/ApiAppUpdateExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/ApiAppUpdateExample.ts
- lang: Java
label: Java
source:
$ref: examples/ApiAppUpdateExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/ApiAppUpdateExample.rb
- lang: Python
label: Python
source:
$ref: examples/ApiAppUpdateExample.py
- lang: cURL
label: cURL
source:
$ref: examples/ApiAppUpdateExample.sh
x-meta:
seo:
title: Update API App | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build custom integrations with a wide range of tools. To find out how to update an App that you own, click here.
delete:
tags:
- Api App
summary: Delete API App
description: Deletes an API App. Can only be invoked for apps you own.
operationId: apiAppDelete
parameters:
- name: client_id
in: path
description: The client id of the API App to delete.
required: true
schema:
type: string
example: 0dd3b823a682527788c4e40cb7b6f7e9
responses:
'204':
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'
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'
404_example:
$ref: '#/components/examples/Error404Response'
4XX_example:
$ref: '#/components/examples/Error4XXResponse'
security:
- api_key: []
- oauth2:
- api_app_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/ApiAppDeleteExample.php
- lang: C#
label: C#
source:
$ref: examples/ApiAppDeleteExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/ApiAppDeleteExample.ts
- lang: Java
label: Java
source:
$ref: examples/ApiAppDeleteExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/ApiAppDeleteExample.rb
- lang: Python
label: Python
source:
$ref: examples/ApiAppDeleteExample.py
- lang: cURL
label: cURL
source:
$ref: examples/ApiAppDeleteExample.sh
x-meta:
seo:
title: Delete API App | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build custom integrations with a wide range of tools. To find out how to delete an API App, click here.
/api_app/list:
get:
tags:
- Api App
summary: List API Apps
description: Returns a list of API Apps that are accessible by you. If you are on a team with an Admin or Developer role, this list will include apps owned by teammates.
operationId: apiAppList
parameters:
- name: page
in: query
description: Which page number of the API App List to return. Defaults to `1`.
schema:
type: integer
default: 1
- name: page_size
in: query
description: Number of objects to be returned per page. Must be between `1` and `100`. Default is `20`.
schema:
type: integer
default: 20
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/ApiAppListResponse'
examples:
example:
$ref: '#/components/examples/ApiAppListResponse'
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:
- api_app_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/ApiAppListExample.php
- lang: C#
label: C#
source:
$ref: examples/ApiAppListExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/ApiAppListExample.ts
- lang: Java
label: Java
source:
$ref: examples/ApiAppListExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/ApiAppListExample.rb
- lang: Python
label: Python
source:
$ref: examples/ApiAppListExample.py
- lang: cURL
label: cURL
source:
$ref: examples/ApiAppListExample.sh
x-meta:
seo:
title: List API Apps | 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 a list of API Apps that are accessible by you, click here.
components:
schemas:
SubOptions:
description: Additional options supported by API App.
properties:
can_insert_everywhere:
description: Determines if signers can use "Insert Everywhere" when signing a document.
type: boolean
default: false
type: object
ApiAppResponse:
description: Contains information about an API App.
properties:
callback_url:
description: The app's callback URL (for events)
type: string
nullable: true
client_id:
description: The app's client id
type: string
created_at:
description: The time that the app was created
type: integer
domains:
description: The domain name(s) associated with the app
type: array
items:
type: string
name:
description: The name of the app
type: string
is_approved:
description: Boolean to indicate if the app has been approved
type: boolean
oauth:
$ref: '#/components/schemas/ApiAppResponseOAuth'
options:
$ref: '#/components/schemas/ApiAppResponseOptions'
owner_account:
$ref: '#/components/schemas/ApiAppResponseOwnerAccount'
white_labeling_options:
$ref: '#/components/schemas/ApiAppResponseWhiteLabelingOptions'
type: object
x-internal-class: true
ApiAppResponseWhiteLabelingOptions:
description: An object with options to customize the app's signer page
properties:
header_background_color:
type: string
legal_version:
type: string
link_color:
type: string
page_background_color:
type: string
primary_button_color:
type: string
primary_button_color_hover:
type: string
primary_button_text_color:
type: string
primary_button_text_color_hover:
type: string
secondary_button_color:
type: string
secondary_button_color_hover:
type: string
secondary_button_text_color:
type: string
secondary_button_text_color_hover:
type: string
text_color1:
type: string
text_color2:
type: string
type: object
nullable: true
x-internal-class: true
ApiAppResponseOAuth:
description: An object describing the app's OAuth properties, or null if OAuth is not configured for the app.
properties:
callback_url:
description: The app's OAuth callback URL.
type: string
secret:
description: The app's OAuth secret, or null if the app does not belong to user.
type: string
nullable: true
scopes:
description: Array of OAuth scopes used by the app.
type: array
items:
type: string
charges_users:
description: Boolean indicating whether the app owner or the account granting permission is billed for OAuth requests.
type: boolean
type: object
nullable: true
x-internal-class: true
ApiAppGetResponse:
required:
- api_app
properties:
api_app:
$ref: '#/components/schemas/ApiAppResponse'
warnings:
description: A list of warnings.
type: array
items:
$ref: '#/components/schemas/WarningResponse'
type: object
x-internal-class: true
SubOAuth:
description: OAuth related parameters.
properties:
callback_url:
description: The callback URL to be used for OAuth flows. (Required if `oauth[scopes]` is provided)
type: string
scopes:
description: A list of [OAuth scopes](/api/reference/tag/OAuth) to be granted to the app. (Required if `oauth[callback_url]` is provided).
type: array
items:
type: string
enum:
- request_signature
- basic_account_info
- account_access
- signature_request_access
- template_access
- team_access
- api_app_access
- ''
type: object
ApiAppResponseOwnerAccount:
description: An object describing the app's owner
properties:
account_id:
description: The owner account's ID
type: string
email_address:
description: The owner account's email address
type: string
type: object
x-internal-class: true
ApiAppListResponse:
required:
- api_apps
- list_info
properties:
api_apps:
description: Contains information about API Apps.
type: array
items:
$ref: '#/components/schemas/ApiAppResponse'
list_info:
$ref: '#/components/schemas/ListInfoResponse'
warnings:
description: A list of warnings.
type: array
items:
$ref: '#/components/schemas/WarningResponse'
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
ApiAppResponseOptions:
description: An object with options that override account settings.
properties:
can_insert_everywhere:
description: Boolean denoting if signers can "Insert Everywhere" in one click while signing a document
type: boolean
type: object
nullable: true
x-internal-class: true
ErrorResponse:
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorResponseError'
type: object
ApiAppCreateRequest:
required:
- name
- domains
properties:
callback_url:
description: The URL at which the ApiApp should receive event callbacks.
type: string
custom_logo_file:
description: An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)
type: string
format: binary
domains:
description: The domain names the ApiApp will be associated with.
type: array
items:
type: string
maxItems: 10
minItems: 1
name:
description: The name you want to assign to the ApiApp.
type: string
oauth:
$ref: '#/components/schemas/SubOAuth'
options:
$ref: '#/components/schemas/SubOptions'
white_labeling_options:
$ref: '#/components/schemas/SubWhiteLabelingOptions'
type: object
SubWhiteLabelingOptions:
description: 'An array of elements and values serialized to a string, to be used to customize the app''s signer page. (Only applies to some API plans)
Take a look at our [white labeling guide](https://developers.hellosign.com/api/reference/premium-branding/) to learn more.'
properties:
header_background_color:
type: string
default: '#1a1a1a'
legal_version:
type: string
default: terms1
enum:
- terms1
- terms2
link_color:
type: string
default: '#0061FE'
page_background_color:
type: string
default: '#f7f8f9'
primary_button_color:
type: string
default: '#0061FE'
primary_button_color_hover:
type: string
default: '#0061FE'
primary_button_text_color:
type: string
default: '#ffffff'
primary_button_text_color_hover:
type: string
default: '#ffffff'
secondary_button_color:
type: string
default: '#ffffff'
secondary_button_color_hover:
type: string
default: '#ffffff'
secondary_button_text_color:
type: string
default: '#0061FE'
secondary_button_text_color_hover:
type: string
default: '#0061FE'
text_color1:
type: string
default: '#808080'
text_color2:
type: string
default: '#ffffff'
reset_to_default:
description: Resets white labeling options to defaults. Only useful when updating an API App.
type: boolean
type: object
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
ListInfoResponse:
description: Contains pagination information about the data returned.
properties:
num_pages:
description: Total number of pages available.
type: integer
num_results:
description: Total number of objects available.
type: integer
nullable: true
page:
description: Number of the page being returned.
type: integer
page_size:
description: Objects returned per page.
type: integer
type: object
x-internal-class: true
ApiAppUpdateRequest:
properties:
callback_url:
description: The URL at which the API App should receive event callbacks.
type: string
custom_logo_file:
description: An image file to use as a custom logo in embedded contexts. (Only applies to some API plans)
type: string
format: binary
domains:
description: The domain names the ApiApp will be associated with.
type: array
items:
type: string
maxItems: 10
name:
description: The name you want to assign to the ApiApp.
type: string
oauth:
$ref: '#/components/schemas/SubOAuth'
options:
$ref: '#/components/schemas/SubOptions'
white_labeling_options:
$ref: '#/components/schemas/SubWhiteLabelingOptions'
type: object
examples:
ApiAppUpdateResponse:
summary: API App Update
value:
$ref: examples/json/ApiAppUpdateResponse.json
ApiAppListResponse:
summary: API App List
value:
$ref: examples/json/ApiAppListResponse.json
Error401Response:
summary: Error 401 unauthorized
value:
$ref: examples/json/Error401Response.json
ApiAppGetResponse:
summary: API App
value:
$ref: examples/json/ApiAppGetResponse.json
Error409Response:
summary: Error 409 conflict
value:
$ref: examples/json/Error409Response.json
Error400Response:
summary: Error 400 bad_request
value:
$ref: examples/json/Error400Response.json
ApiAppCreateResponse:
summary: API App
value:
$ref: examples/json/ApiAppCreateResponse.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
Error404Response:
summary: Error 404 not_found
value:
$ref: examples/json/Error404Response.json
ApiAppCreateRequest:
summary: Default Example
value:
$ref: examples/json/ApiAppCreateRequest.json
Error403Response:
summary: Error 403 forbidden
value:
$ref: examples/json/Error403Response.json
Error429Response:
summary: Error 429 exceeded_rate
value:
$ref: examples/json/Error429Response.json
ApiAppUpdateRequest:
summary: Default Example
value:
$ref: examples/json/ApiAppUpdateRequest.json
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: '#/compo
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hellosign/refs/heads/main/openapi/hellosign-api-app-api-openapi.yml