openapi: 3.1.0
info:
  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