OpenAPI Specification
openapi: 3.1.0
info:
title: Box Sign Templates API
description: Needs a description.
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:
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'
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
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 protected]
description: Content of the email footer.
tags:
- name: Sign Templates