Dropbox Sign (HelloSign) Bulk Send Job API
{'$ref': './markdown/en/tags/bulk-send-job-tag-description.md'}
OpenAPI Specification
openapi: 3.0.3
info:
title: Dropbox Sign Account Bulk Send Job 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: Bulk Send Job
description:
$ref: ./markdown/en/tags/bulk-send-job-tag-description.md
paths:
/bulk_send_job/{bulk_send_job_id}:
get:
tags:
- Bulk Send Job
summary: Get Bulk Send Job
description: Returns the status of the BulkSendJob and its SignatureRequests specified by the `bulk_send_job_id` parameter.
operationId: bulkSendJobGet
parameters:
- name: bulk_send_job_id
in: path
description: The id of the BulkSendJob to retrieve.
required: true
schema:
type: string
example: 6e683bc0369ba3d5b6f43c2c22a8031dbf6bd174
- name: page
in: query
description: Which page number of the BulkSendJob 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/BulkSendJobGetResponse'
examples:
example:
$ref: '#/components/examples/BulkSendJobGetResponse'
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:
- request_signature
- signature_request_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/BulkSendJobGetExample.php
- lang: C#
label: C#
source:
$ref: examples/BulkSendJobGetExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/BulkSendJobGetExample.ts
- lang: Java
label: Java
source:
$ref: examples/BulkSendJobGetExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/BulkSendJobGetExample.rb
- lang: Python
label: Python
source:
$ref: examples/BulkSendJobGetExample.py
- lang: cURL
label: cURL
source:
$ref: examples/BulkSendJobGetExample.sh
x-meta:
seo:
title: Get Bulk Send Job | API Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build custom integrations. To find out how to return the status of the BulkSendJob and SignatureRequests, click here.
/bulk_send_job/list:
get:
tags:
- Bulk Send Job
summary: List Bulk Send Jobs
description: Returns a list of BulkSendJob that you can access.
operationId: bulkSendJobList
parameters:
- name: page
in: query
description: Which page number of the BulkSendJob 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/BulkSendJobListResponse'
examples:
example:
$ref: '#/components/examples/BulkSendJobListResponse'
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:
- request_signature
- signature_request_access
x-codeSamples:
- lang: PHP
label: PHP
source:
$ref: examples/BulkSendJobListExample.php
- lang: C#
label: C#
source:
$ref: examples/BulkSendJobListExample.cs
- lang: TypeScript
label: TypeScript
source:
$ref: examples/BulkSendJobListExample.ts
- lang: Java
label: Java
source:
$ref: examples/BulkSendJobListExample.java
- lang: Ruby
label: Ruby
source:
$ref: examples/BulkSendJobListExample.rb
- lang: Python
label: Python
source:
$ref: examples/BulkSendJobListExample.py
- lang: cURL
label: cURL
source:
$ref: examples/BulkSendJobListExample.sh
x-meta:
seo:
title: List Bulk Send Jobs | Documentation | Dropbox Sign for Developers
description: The Dropbox Sign API allows you to build custom integrations. To find out how to return a list of BulkSendJob that you can access, click here.
components:
examples:
Error401Response:
summary: Error 401 unauthorized
value:
$ref: examples/json/Error401Response.json
BulkSendJobGetResponse:
summary: Bulk Send Job
value:
$ref: examples/json/BulkSendJobGetResponse.json
BulkSendJobListResponse:
summary: Bulk Send Job List
value:
$ref: examples/json/BulkSendJobListResponse.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
Error403Response:
summary: Error 403 forbidden
value:
$ref: examples/json/Error403Response.json
Error429Response:
summary: Error 429 exceeded_rate
value:
$ref: examples/json/Error429Response.json
schemas:
SignatureRequestResponseAttachment:
description: Signer attachments.
required:
- id
- signer
- name
- required
properties:
id:
description: The unique ID for this attachment.
type: string
signer:
description: The Signer this attachment is assigned to.
type: string
x-int-or-string: true
name:
description: The name of this attachment.
type: string
required:
description: A boolean value denoting if this attachment is required.
type: boolean
instructions:
description: Instructions for Signer.
type: string
nullable: true
uploaded_at:
description: Timestamp when attachment was uploaded by Signer.
type: integer
nullable: true
type: object
x-internal-class: true
BulkSendJobResponse:
description: Contains information about the BulkSendJob such as when it was created and how many signature requests are queued.
properties:
bulk_send_job_id:
description: The id of the BulkSendJob.
type: string
nullable: true
total:
description: The total amount of Signature Requests queued for sending.
type: integer
is_creator:
description: True if you are the owner of this BulkSendJob, false if it's been shared with you by a team member.
type: boolean
created_at:
description: Time that the BulkSendJob was created.
type: integer
type: object
x-internal-class: true
SignatureRequestResponseCustomFieldBase:
description: 'An array of Custom Field objects containing the name and type of each custom field.
* Text Field uses `SignatureRequestResponseCustomFieldText`
* Checkbox Field uses `SignatureRequestResponseCustomFieldCheckbox`'
required:
- name
- type
properties:
type:
description: The type of this Custom Field. Only 'text' and 'checkbox' are currently supported.
type: string
name:
description: The name of the Custom Field.
type: string
required:
description: A boolean value denoting if this field is required.
type: boolean
api_id:
description: The unique ID for this field.
type: string
editor:
description: The name of the Role that is able to edit this field.
type: string
nullable: true
type: object
discriminator:
propertyName: type
mapping:
text: '#/components/schemas/SignatureRequestResponseCustomFieldText'
checkbox: '#/components/schemas/SignatureRequestResponseCustomFieldCheckbox'
x-internal-class: true
x-base-class: true
BulkSendJobListResponse:
required:
- bulk_send_jobs
- list_info
properties:
bulk_send_jobs:
description: Contains a list of BulkSendJobs that the API caller has access to.
type: array
items:
$ref: '#/components/schemas/BulkSendJobResponse'
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
BulkSendJobGetResponseSignatureRequests:
title: BulkSendJobGetResponseSignatureRequests
type: object
allOf:
- $ref: '#/components/schemas/SignatureRequestResponse'
- properties:
bulk_send_job_id:
description: The id of the BulkSendJob.
type: string
metadata:
description: The metadata attached to the signature request.
type: object
additionalProperties: {}
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
BulkSendJobGetResponse:
required:
- bulk_send_job
- list_info
- signature_requests
properties:
bulk_send_job:
$ref: '#/components/schemas/BulkSendJobResponse'
list_info:
$ref: '#/components/schemas/ListInfoResponse'
signature_requests:
description: Contains information about the Signature Requests sent in bulk.
type: array
items:
$ref: '#/components/schemas/BulkSendJobGetResponseSignatureRequests'
warnings:
description: A list of warnings.
type: array
items:
$ref: '#/components/schemas/WarningResponse'
type: object
x-internal-class: true
SignatureRequestResponse:
description: Contains information about a signature request.
properties:
test_mode:
description: Whether this is a test signature request. Test requests have no legal value. Defaults to `false`.
type: boolean
default: false
signature_request_id:
description: The id of the SignatureRequest.
type: string
requester_email_address:
description: The email address of the initiator of the SignatureRequest.
type: string
nullable: true
title:
description: The title the specified Account uses for the SignatureRequest.
type: string
original_title:
description: Default Label for account.
type: string
subject:
description: The subject in the email that was initially sent to the signers.
type: string
nullable: true
message:
description: The custom message in the email that was initially sent to the signers.
type: string
nullable: true
metadata:
description: The metadata attached to the signature request.
type: object
additionalProperties: {}
created_at:
description: Time the signature request was created.
type: integer
expires_at:
description: The time when the signature request will expire unsigned signatures. See [Signature Request Expiration Date](https://developers.hellosign.com/docs/signature-request/expiration/) for details.
type: integer
nullable: true
is_complete:
description: Whether or not the SignatureRequest has been fully executed by all signers.
type: boolean
is_declined:
description: Whether or not the SignatureRequest has been declined by a signer.
type: boolean
has_error:
description: Whether or not an error occurred (either during the creation of the SignatureRequest or during one of the signings).
type: boolean
files_url:
description: The URL where a copy of the request's documents can be downloaded.
type: string
signing_url:
description: The URL where a signer, after authenticating, can sign the documents. This should only be used by users with existing Dropbox Sign accounts as they will be required to log in before signing.
type: string
nullable: true
details_url:
description: The URL where the requester and the signers can view the current status of the SignatureRequest.
type: string
cc_email_addresses:
description: A list of email addresses that were CCed on the SignatureRequest. They will receive a copy of the final PDF once all the signers have signed.
type: array
items:
type: string
signing_redirect_url:
description: The URL you want the signer redirected to after they successfully sign.
type: string
nullable: true
final_copy_uri:
description: The path where the completed document can be downloaded
type: string
nullable: true
template_ids:
description: Templates IDs used in this SignatureRequest (if any).
type: array
items:
type: string
nullable: true
custom_fields:
description: 'An array of Custom Field objects containing the name and type of each custom field.
* Text Field uses `SignatureRequestResponseCustomFieldText`
* Checkbox Field uses `SignatureRequestResponseCustomFieldCheckbox`'
type: array
items:
$ref: '#/components/schemas/SignatureRequestResponseCustomFieldBase'
nullable: true
attachments:
description: Signer attachments.
type: array
items:
$ref: '#/components/schemas/SignatureRequestResponseAttachment'
nullable: true
response_data:
description: An array of form field objects containing the name, value, and type of each textbox or checkmark field filled in by the signers.
type: array
items:
$ref: '#/components/schemas/SignatureRequestResponseDataBase'
nullable: true
signatures:
description: An array of signature objects, 1 for each signer.
type: array
items:
$ref: '#/components/schemas/SignatureRequestResponseSignatures'
bulk_send_job_id:
description: The ID of the Bulk Send job which sent the signature request, if applicable.
type: string
nullable: true
type: object
x-internal-class: true
SignatureRequestResponseSignatures:
description: An array of signature objects, 1 for each signer.
properties:
signature_id:
description: Signature identifier.
type: string
signer_group_guid:
description: Signer Group GUID
type: string
nullable: true
signer_email_address:
description: The email address of the signer.
type: string
signer_name:
description: The name of the signer.
type: string
nullable: true
signer_role:
description: The role of the signer.
type: string
nullable: true
order:
description: If signer order is assigned this is the 0-based index for this signer.
type: integer
nullable: true
status_code:
description: 'The current status of the signature. eg: awaiting_signature, signed, declined.'
type: string
decline_reason:
description: The reason provided by the signer for declining the request.
type: string
nullable: true
signed_at:
description: Time that the document was signed or null.
type: integer
nullable: true
last_viewed_at:
description: The time that the document was last viewed by this signer or null.
type: integer
nullable: true
last_reminded_at:
description: The time the last reminder email was sent to the signer or null.
type: integer
nullable: true
has_pin:
description: Boolean to indicate whether this signature requires a PIN to access.
type: boolean
has_sms_auth:
description: Boolean to indicate whether this signature has SMS authentication enabled.
type: boolean
nullable: true
has_sms_delivery:
description: Boolean to indicate whether this signature has SMS delivery enabled.
type: boolean
nullable: true
sms_phone_number:
description: The SMS phone number used for authentication or signature request delivery.
type: string
nullable: true
reassigned_by:
description: Email address of original signer who reassigned to this signer.
type: string
nullable: true
reassignment_reason:
description: Reason provided by original signer who reassigned to this signer.
type: string
nullable: true
reassigned_from:
description: Previous signature identifier.
type: string
nullable: true
error:
description: Error message pertaining to this signer, or null.
type: string
nullable: true
type: object
x-internal-class: true
ErrorResponse:
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorResponseError'
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
SignatureRequestResponseDataBase:
description: An array of form field objects containing the name, value, and type of each textbox or checkmark field filled in by the signers.
properties:
api_id:
description: The unique ID for this field.
type: string
signature_id:
description: The ID of the signature to which this response is linked.
type: string
name:
description: The name of the form field.
type: string
required:
description: A boolean value denoting if this field is required.
type: boolean
type:
type: string
type: object
discriminator:
propertyName: type
mapping:
text: '#/components/schemas/SignatureRequestResponseDataValueText'
checkbox: '#/components/schemas/SignatureRequestResponseDataValueCheckbox'
dropdown: '#/components/schemas/SignatureRequestResponseDataValueDropdown'
radio: '#/components/schemas/SignatureRequestResponseDataValueRadio'
signature: '#/components/schemas/SignatureRequestResponseDataValueSignature'
date_signed: '#/components/schemas/SignatureRequestResponseDataValueDateSigned'
initials: '#/components/schemas/SignatureRequestResponseDataValueInitials'
text-merge: '#/components/schemas/SignatureRequestResponseDataValueTextMerge'
checkbox-merge: '#/components/schemas/SignatureRequestResponseDataValueCheckboxMerge'
x-internal-class: true
x-base-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/EventCallbackSignatureRequestReass
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hellosign/refs/heads/main/openapi/hellosign-bulk-send-job-api-openapi.yml