openapi: 3.1.0
info:
version: "1.0"
title: Box Authorize Authorization Sign Templates API
description: Needs a description.
tags:
- name: Sign Templates
description: 'Sign templates allow you to use a predefined Box Sign
template when creating a sign request.
The template includes placeholders that
are automatically populated with data when creating the request.'
x-box-tag: sign_templates
paths:
/sign_templates:
get:
operationId: get_sign_templates
summary: List Box Sign templates
tags:
- Sign Templates
x-box-tag: sign_templates
description: Gets Box Sign templates created by a user.
parameters:
- name: marker
description: 'Defines the position marker at which to begin returning results. This is
used when paginating using marker-based pagination.
This requires `usemarker` to be set to `true`.'
in: query
required: false
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
schema:
type: string
- name: limit
description: The maximum number of items to return per page.
in: query
required: false
example: 1000
schema:
type: integer
format: int64
maximum: 1000
responses:
'200':
description: Returns a collection of templates.
content:
application/json:
schema:
$ref: '#/components/schemas/SignTemplates'
'401':
description: 'Returned when the access token provided in the `Authorization` header
is not recognized or not provided.'
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/sign_templates/{template_id}:
get:
operationId: get_sign_templates_id
summary: Get Box Sign template by ID
tags:
- Sign Templates
x-box-tag: sign_templates
description: Fetches details of a specific Box Sign template.
parameters:
- name: template_id
description: The ID of a Box Sign template.
example: 123075213-7d117509-8f05-42e4-a5ef-5190a319d41d
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns details of a template.
content:
application/json:
schema:
$ref: '#/components/schemas/SignTemplate'
'401':
description: 'Returned when the access token provided in the `Authorization` header
is not recognized or not provided.'
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: 'Returned if the template is not found or the user does not
have access to the associated template.'
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
SignTemplate:
title: Box Sign template
type: object
x-box-resource-id: sign_template
x-box-tag: sign_templates
description: A Box Sign template object
allOf:
- properties:
type:
type: string
example: sign-template
enum:
- sign-template
description: object type
id:
type: string
example: 4206996024-14944f75-c34b-478a-95a1-264b1ff80d35
description: Template identifier.
name:
type: string
nullable: true
example: Official contract
description: The name of the template.
email_subject:
type: string
example: Sign Request from Acme
description: Subject of signature request email. This is cleaned by sign request. If this field is not passed, a default subject will be used.
nullable: true
email_message:
type: string
example: Hello! Please sign the document below
description: Message to include in signature request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used.
nullable: true
days_valid:
type: integer
description: Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire.
minimum: 0
maximum: 730
example: 2
nullable: true
parent_folder:
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- description: 'The destination folder to place final, signed document and signing
log. Only `ID` and `type` fields are required. The root folder,
folder ID `0`, cannot be used.'
source_files:
type: array
items:
$ref: '#/components/schemas/File--Mini'
description: List of files to create a signing document from. Only the ID and type fields are required for each file.
are_fields_locked:
type: boolean
description: Indicates if the template input fields are editable or not.
example: false
are_options_locked:
type: boolean
description: Indicates if the template document options are editable or not, for example renaming the document.
example: true
are_recipients_locked:
type: boolean
description: Indicates if the template signers are editable or not.
example: false
are_email_settings_locked:
type: boolean
description: Indicates if the template email settings are editable or not.
example: true
are_files_locked:
type: boolean
description: Indicates if the template files are editable or not. This includes deleting or renaming template files.
example: true
signers:
type: array
items:
$ref: '#/components/schemas/TemplateSigner'
description: Array of signers for the template.
additional_info:
description: Additional information on which fields are required and which fields are not editable.
type: object
properties:
non_editable:
type: array
description: Non editable fields.
items:
type: string
enum:
- email_subject
- email_message
- name
- days_valid
- signers
- source_files
example:
- email_subject
- name
required:
type: object
description: Required fields.
properties:
signers:
description: Required signer fields.
example:
- - email
- - email
type: array
items:
type: array
items:
type: string
enum:
- email
example:
- email
ready_sign_link:
nullable: true
description: 'Box''s ready-sign link feature enables you to create a link to a signature request that you''ve created from a template. Use this link when you want to post a signature request on a public form — such as an email, social media post, or web page — without knowing who the signers will be. Note: The ready-sign link feature is limited to Enterprise Plus customers and not available to Box Verified Enterprises.'
type: object
properties:
url:
type: string
description: The URL that can be sent to signers.
example: '"https://app.box.com/sign/
ready-sign-link/a1cdf2c7-fa81-4a67-8163-1e5f4dbe5178"'
name:
type: string
nullable: true
description: Request name.
example: Official contract
instructions:
type: string
nullable: true
description: Extra instructions for all signers.
example: Hello! Please sign the document below
folder_id:
type: string
nullable: true
example: '12345'
description: 'The destination folder to place final,
signed document and signing
log. Only `ID` and `type` fields are required.
The root folder,
folder ID `0`, cannot be used.'
is_notification_disabled:
type: boolean
description: 'Whether to disable notifications when
a signer has signed.'
example: true
is_active:
type: boolean
description: Whether the ready sign link is enabled or not.
example: false
custom_branding:
nullable: true
type: object
description: 'Custom branding applied to notifications
and signature requests.'
properties:
company_name:
description: Name of the company
type: string
nullable: true
example: Corporation inc.
logo_uri:
type: string
nullable: true
description: Custom branding logo URI in the form of a base64 image.
example: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA
AAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A
8AAQUBAScY42YAAAAASUVORK5CYII='
branding_color:
type: string
nullable: true
example: 9E5E6F
description: Custom branding color in hex.
email_footer_text:
type: string
nullable: true
example: Contact email email@mail.com
description: Content of the email footer.
TemplateSigner:
title: Signer fields for Templates
type: object
description: The schema for a Signer for Templates
allOf:
- properties:
inputs:
type: array
items:
$ref: '#/components/schemas/TemplateSignerInput'
readOnly: true
email:
type: string
description: Email address of the signer
example: example@mail.com
nullable: true
role:
type: string
enum:
- signer
- approver
- final_copy_reader
description: 'Defines the role of the signer in the signature request. A role of
`signer` needs to sign the document, a role `approver`
approves the document and
a `final_copy_reader` role only
receives the final signed document and signing log.'
example: signer
default: signer
is_in_person:
type: boolean
description: 'Used in combination with an embed URL for a sender.
After the sender signs, they will be
redirected to the next `in_person` signer.'
example: true
order:
type: integer
description: Order of the signer
minimum: 0
example: 2
signer_group_id:
type: string
description: 'If provided, this value points signers that are assigned the same inputs and belongs to same signer group.
A signer group is not a Box Group. It is an entity that belongs to the template itself and can only be used
within Sign Requests created from it.'
example: cd4ff89-8fc1-42cf-8b29-1890dedd26d7
nullable: true
Folder--Base:
title: Folder (Base)
type: object
x-box-resource-id: folder--base
x-box-sanitized: true
x-box-tag: folders
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
description: 'The bare basic representation of a folder, the minimal
amount of fields returned when using the `fields` query
parameter.'
required:
- id
- type
properties:
id:
type: string
nullable: false
description: 'The unique identifier that represent a folder.
The ID for any folder can be determined
by visiting a folder in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/folders/123`
the `folder_id` is `123`.'
example: '12345'
etag:
type: string
nullable: true
example: '1'
description: 'The HTTP `etag` of this folder. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the folder if (no) changes have happened.'
type:
type: string
description: '`folder`'
example: folder
enum:
- folder
nullable: false
Folder--Mini:
title: Folder (Mini)
type: object
x-box-resource-id: folder--mini
x-box-variant: mini
description: 'A mini representation of a file version, used when
nested under another resource.'
allOf:
- $ref: '#/components/schemas/Folder--Base'
- properties:
sequence_id:
allOf:
- type: string
example: '3'
nullable: true
description: 'A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.'
- nullable: false
name:
type: string
description: The name of the folder.
example: Contracts
nullable: false
File--Base:
title: File (Base)
type: object
x-box-resource-id: file--base
x-box-sanitized: true
x-box-tag: files
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
nullable: true
description: 'The bare basic representation of a file, the minimal
amount of fields returned when using the `fields` query
parameter.'
required:
- id
- type
properties:
id:
type: string
nullable: false
description: 'The unique identifier that represent a file.
The ID for any file can be determined
by visiting a file in the web application
and copying the ID from the URL. For example,
for the URL `https://*.app.box.com/files/123`
the `file_id` is `123`.'
example: '12345'
etag:
type: string
example: '1'
nullable: true
description: 'The HTTP `etag` of this file. This can be used within some API
endpoints in the `If-Match` and `If-None-Match` headers to only
perform changes on the file if (no) changes have happened.'
type:
type: string
description: '`file`'
example: file
enum:
- file
nullable: false
FileVersion--Mini:
title: File version (Mini)
type: object
x-box-resource-id: file_version--mini
x-box-variant: mini
description: 'A mini representation of a file version, used when
nested within another resource.'
allOf:
- $ref: '#/components/schemas/FileVersion--Base'
- properties:
sha1:
type: string
description: The SHA1 hash of this version of the file.
example: 134b65991ed521fcfe4724b7d814ab8ded5185dc
File--Mini:
title: File (Mini)
type: object
x-box-resource-id: file--mini
x-box-variant: mini
description: 'A mini representation of a file, used when
nested under another resource.'
nullable: true
allOf:
- $ref: '#/components/schemas/File--Base'
- properties:
sequence_id:
allOf:
- type: string
example: '3'
nullable: true
description: 'A numeric identifier that represents the most recent user event
that has been applied to this item.
This can be used in combination with the `GET /events`-endpoint
to filter out user events that would have occurred before this
identifier was read.
An example would be where a Box Drive-like application
would fetch an item via the API, and then listen to incoming
user events for changes to the item. The application would
ignore any user events where the `sequence_id` in the event
is smaller than or equal to the `sequence_id` in the originally
fetched resource.'
- nullable: false
name:
type: string
description: The name of the file
example: Contract.pdf
sha1:
type: string
format: digest
nullable: false
example: 85136C79CBF9FE36BB9D05D0639C70C265C18D37
description: 'The SHA1 hash of the file. This can be used to compare the contents
of a file on Box with a local file.'
file_version:
allOf:
- $ref: '#/components/schemas/FileVersion--Mini'
- description: The information about the current version of the file.
SignTemplates:
title: Box Sign templates
type: object
x-box-resource-id: sign_templates
x-box-tag: sign_templates
description: 'A list of templates, as returned from any Box Sign
API endpoints by default.'
allOf:
- type: object
description: 'The part of an API response that describes marker
based pagination'
properties:
limit:
description: 'The limit that was used for these entries. This will be the same as the
`limit` query parameter unless that value exceeded the maximum value
allowed. The maximum value varies by API.'
example: 1000
type: integer
format: int64
next_marker:
description: The marker for the start of the next page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
type: string
nullable: true
prev_marker:
description: The marker for the start of the previous page of results.
example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
type: string
nullable: true
- properties:
entries:
type: array
description: A list of templates.
items:
$ref: '#/components/schemas/SignTemplate'
SignRequestPrefillTag:
title: Sign Request Prefill Tag
type: object
description: 'Prefill tags are used to prefill placeholders with signer input data. Only
one value field can be included.'
properties:
document_tag_id:
type: string
example: '1234'
description: This references the ID of a specific tag contained in a file of the sign request.
nullable: true
text_value:
type: string
example: text
description: Text prefill value
nullable: true
checkbox_value:
type: boolean
example: true
description: Checkbox prefill value
nullable: true
date_value:
type: string
format: date
example: '2021-04-26'
description: Date prefill value
nullable: true
FileVersion--Base:
title: File version (Base)
type: object
x-box-resource-id: file_version--base
x-box-sanitized: true
x-box-variants:
- base
- mini
- standard
- full
x-box-variant: base
description: 'The bare basic representation of a file version, the minimal
amount of fields returned when using the `fields` query
parameter.'
required:
- id
- type
properties:
id:
type: string
nullable: false
description: The unique identifier that represent a file version.
example: '12345'
type:
type: string
description: '`file_version`'
example: file_version
enum:
- file_version
nullable: false
ClientError:
title: Client error
type: object
x-box-resource-id: client_error
description: A generic error
properties:
type:
description: error
example: error
type: string
enum:
- error
nullable: false
status:
description: The HTTP status of the response.
example: 400
type: integer
format: int32
nullable: false
code:
description: A Box-specific error code
example: item_name_invalid
type: string
enum:
- created
- accepted
- no_content
- redirect
- not_modified
- bad_request
- unauthorized
- forbidden
- not_found
- method_not_allowed
- conflict
- precondition_failed
- too_many_requests
- internal_server_error
- unavailable
- item_name_invalid
- insufficient_scope
message:
description: A short message describing the error.
example: Method Not Allowed
type: string
nullable: false
context_info:
description: 'A free-form object that contains additional context
about the error. The possible fields are defined on
a per-endpoint basis. `message` is only one example.'
type: object
nullable: true
properties:
message:
type: string
description: More details on the error.
example: Something went wrong.
help_url:
description: A URL that links to more information about why this error occurred.
example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
type: string
nullable: false
request_id:
description: 'A unique identifier for this response, which can be used
when contacting Box support.'
type: string
example: abcdef123456
nullable: false
TemplateSignerInput:
title: Template Signer Input
type: object
description: Input created by a Signer on a Template
required:
- page_index
allOf:
- $ref: '#/components/schemas/SignRequestPrefillTag'
- properties:
type:
type: string
enum:
- signature
- date
- text
- checkbox
- attachment
- radio
- dropdown
description: Type of input
example: text
content_type:
type: string
enum:
- signature
- initial
- stamp
- date
- checkbox
- text
- full_name
- first_name
- last_name
- company
- title
- email
- attachment
- radio
- dropdown
description: Content type of input
example: text
is_required:
type: boolean
description: Whether or not the input is required.
example: true
page_index:
type: integer
description: Index of page that the input is on.
example: 4
document_id:
type: string
description: Document identifier.
example: 123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7
nullable: true
dropdown_choices:
type: array
example:
- 'Yes'
- 'No'
- Maybe
description: When the input is of the type `dropdown` this values will be filled with all the dropdown options.
nullable: true
items:
type: string
group_id:
type: string
description: When the input is of type `radio` they can be grouped to gather with this identifier.
nullable: true
example: da317330-225a-4c72-89ad-0d6dcaaf4df6
coordinates:
type: object
description: Where the input is located on a page.
properties:
x:
type: number
example: 0.672258592471358
description: Relative x coordinate to the page the input is on, ranging from 0 to 1.
y:
type: number
example: 0.18654283173599448
description: Relative y coordinate to the page the input is on, ranging from 0 to 1.
dimensions:
type: object
description: The size of the input.
properties:
width:
type: number
example: 0.2618657937806874
description: Relative width to the page the input is on, ranging from 0 to 1.
height:
type: number
example: 0.05311728090109673
description: Relative height to the page the input is on, ranging from 0 to 1.
label:
type: string
description: The label field is used especially for text, attachment, radio, and checkbox type inputs.
nullable: true
example: Legal name
read_only:
type: boolean
description: Whether this input was defined as read-only(immutable by signers) or not
example: true