OpenAPI Specification
openapi: 3.1.0
info:
title: Box Sign Requests API
description: Needs a description.
paths:
/sign_requests/{sign_request_id}/cancel:
post:
operationId: post_sign_requests_id_cancel
summary: Box Cancel sign request
tags:
- Sign Requests
x-box-tag: sign_requests
description: Cancels a sign request.
parameters:
- name: sign_request_id
description: The ID of the sign request
example: '33243242'
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns a Sign Request object.
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequest'
'404':
description: >-
Returns an error when the sign request cannot be found or the user
does
not have access to the sign request.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/sign_requests/{sign_request_id}/resend:
post:
operationId: post_sign_requests_id_resend
summary: Box Resend sign request
tags:
- Sign Requests
x-box-tag: sign_requests
description: Resends a sign request email to all outstanding signers.
parameters:
- name: sign_request_id
description: The ID of the sign request
example: '33243242'
in: path
required: true
schema:
type: string
responses:
'202':
description: |-
Returns an empty response when the API call was successful.
The email notifications will be sent asynchronously.
'404':
description: >-
Returns an error when the sign request cannot be found or the user
does
not have access to the sign request.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/sign_requests/{sign_request_id}:
get:
operationId: get_sign_requests_id
summary: Box Get sign request by ID
tags:
- Sign Requests
x-box-tag: sign_requests
description: Gets a sign request by ID.
parameters:
- name: sign_request_id
description: The ID of the sign request
example: '33243242'
in: path
required: true
schema:
type: string
responses:
'200':
description: Returns a sign request
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequest'
'404':
description: >-
Returns an error when the sign request cannot be found, the user
does
not have access to the sign request, or `sign_files` and/or
`parent_folder` is deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
/sign_requests:
get:
operationId: get_sign_requests
summary: Box List sign requests
tags:
- Sign Requests
x-box-tag: sign_requests
description: >-
Gets sign requests created by a user. If the `sign_files` and/or
`parent_folder` are deleted, the sign request will not return in the
list.
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 sign requests
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequests'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
post:
operationId: post_sign_requests
summary: Box Create sign request
tags:
- Sign Requests
x-box-tag: sign_requests
description: >-
Creates a sign request. This involves preparing a document for signing
and
sending the sign request to signers.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequestCreateRequest'
responses:
'201':
description: Returns a Sign Request object.
content:
application/json:
schema:
$ref: '#/components/schemas/SignRequest'
default:
description: An unexpected client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
components:
schemas:
SignRequest:
title: Sign Request
type: object
x-box-resource-id: sign_request
x-box-tag: sign_requests
x-box-variants:
- standard
- base
x-box-variant: standard
description: A Sign Request Object
allOf:
- $ref: '#/components/schemas/SignRequest--Base'
- properties:
type:
type: string
example: sign-request
enum:
- sign-request
description: object type
source_files:
type: array
items:
$ref: '#/components/schemas/File--Base'
description: >-
List of files to create a signing document from. This is
currently limited to ten files. Only the ID and type fields are
required for each file.
signers:
type: array
items:
$ref: '#/components/schemas/SignRequestSigner'
description: Array of signers for the sign request
signature_color:
type: string
example: blue
description: Force a specific color for the signature (blue, black, or red).
nullable: true
id:
type: string
example: '12345'
description: Sign request ID
prepare_url:
type: string
example: https://prepareurl.com
description: >-
This URL is returned if `is_document_preparation_needed` is
set to `true` in the request. It is used to prepare the sign
request
via UI. The sign request is not sent until preparation is
complete.
nullable: true
signing_log:
allOf:
- $ref: '#/components/schemas/File--Mini'
- description: >-
Reference to a file that holds a log of all signer activity
for
the request
status:
type: string
enum:
- converting
- created
- sent
- viewed
- signed
- cancelled
- declined
- error_converting
- error_sending
- expired
- finalizing
- error_finalizing
example: converting
description: Describes the status of the sign request
sign_files:
type: object
properties:
files:
type: array
items:
$ref: '#/components/schemas/File--Mini'
is_ready_for_download:
type: boolean
example: true
description: |-
Indicates whether the `sign_files` documents are processing
and the PDFs may be out of date. A change to any document
requires processing on all `sign_files`. We
recommended waiting until processing is finished
(and this value is true) before downloading the PDFs.
description: >-
List of files that will be signed, which are copies of the
original
source files. A new version of these files are created as
signers sign
and can be downloaded at any point in the signing process.
auto_expire_at:
type: string
format: date-time
example: '2021-04-26T08:12:13.982Z'
description: >-
Uses `days_valid` to calculate the date and time, in GMT, the
sign request will expire if unsigned.
nullable: true
parent_folder:
nullable: false
allOf:
- $ref: '#/components/schemas/Folder--Mini'
- description: >-
The destination folder to place final, signed document and
signing
log.
When this value was not passed in when the signature request
was
created, then we will use a default folder which is either
the parent
folder of the first source file in the payload if we have
the permission
to upload to that folder or a folder called "My Sign
Requests".
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
SignRequests:
title: Box Sign
type: object
x-box-resource-id: sign_requests
x-box-tag: sign_requests
description: >-
A standard representation of a sign request, 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
- properties:
entries:
type: array
description: A list of sign requests
items:
$ref: '#/components/schemas/SignRequest'
tags:
- name: Sign Requests