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