openapi: 3.0.0
info:
  contact:
    email: contact@yousign.com
    name: Support
    url: https://yousign.com/contact
  description: Build the best experience of digital signature through your own platform. Increase your conversion rates, leverage your data and reduce your costs with Yousign API.
  license:
    name: proprietary
    url: https://yousign.com/terms
  title: Public Api v3 Applicant Deprecated API
  version: '3.0'
servers:
- description: Sandbox URL
  url: https://api-sandbox.yousign.app/v3
- description: Production URL
  url: https://api.yousign.app/v3
security:
- bearerAuth: []
tags:
- description: Operations that are no longer recommended for use.
  name: Deprecated
paths:
  /documents:
    post:
      deprecated: true
      description: Deprecated endpoint, do not use.
      operationId: post-documents
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateDocumentFromMultipart'
        description: Upload a Document
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
          description: Created
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
          description: Bad request
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
          description: Access unauthorized
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
          description: Access forbidden
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: This method is not allowed
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsupportedMediaTypeResponse'
          description: UnsupportedMediaType
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsResponse'
          description: Too Many Requests, please try again later.
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
            Retry-After:
              $ref: '#/components/headers/retry-after'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/rateLimit-limit'
            X-RateLimit-Limit-Hour:
              $ref: '#/components/headers/rateLimit-limit-hour'
            X-RateLimit-Limit-Minute:
              $ref: '#/components/headers/rateLimit-limit-minute'
            RateLimit-Remaining:
              $ref: '#/components/headers/rateLimit-remaining'
            X-RateLimit-Remaining-Hour:
              $ref: '#/components/headers/rateLimit-remaining-hour'
            X-RateLimit-Remaining-Minute:
              $ref: '#/components/headers/rateLimit-remaining-minute'
            RateLimit-Reset:
              $ref: '#/components/headers/rateLimit-reset'
      summary: '[DEPRECATED] Upload a Document'
      tags:
      - Deprecated
      x-readme:
        samples-enabled: false
        explorer-enabled: false
components:
  headers:
    rateLimit-remaining:
      description: The number of requests remaining in the current rate limit window
      schema:
        type: integer
    rateLimit-reset:
      description: The remaining time until the rate limit resets in seconds
      schema:
        type: integer
    rateLimit-remaining-hour:
      description: The number of requests remaining in the current hour rate limit window
      schema:
        type: integer
    rateLimit-limit:
      description: The maximum number of requests that the consumer is permitted to make in a given period
      schema:
        type: integer
    retry-after:
      description: Retry the request after X seconds
      schema:
        type: integer
    rateLimit-remaining-minute:
      description: The number of requests remaining in the current minute rate limit window
      schema:
        type: integer
    rateLimit-limit-minute:
      description: The maximum number of requests that the consumer is permitted to make in an minute window
      schema:
        type: integer
    rateLimit-limit-hour:
      description: The maximum number of requests that the consumer is permitted to make in an hour window
      schema:
        type: integer
  schemas:
    DocumentExcludedApprovers:
      description: 'List of Approver IDs who cannot see this Document. When omitted, all Approvers can see it (default). Only available when the document_visibility feature is enabled on the organization.

        '
      example:
      - 550e8400-e29b-41d4-a716-446655440000
      - 6ba7b810-9dad-11d1-80b4-00c04fd430c8
      items:
        format: uuid
        type: string
      type: array
    InternalServerError:
      properties:
        type:
          example: about:blank
          type: string
        detail:
          example: Something wrong occurred.
          type: string
      required:
      - detail
      - type
      title: InternalServerError
      type: object
    TooManyRequestsResponse:
      properties:
        message:
          type: string
      required:
      - message
      title: TooManyRequestsResponse
      type: object
    Document_initials_per_page_inner:
      properties:
        page:
          description: Page number.
          minimum: 1
          type: integer
        y:
          description: Y-axis position of the initials on the page.
          minimum: 0
          type: integer
      required:
      - page
      - y
      type: object
    UnsupportedMediaTypeResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: UnsupportedMediaTypeResponse
      type: object
    CreateDocumentFromMultipart:
      properties:
        file:
          description: 'Binary file. Accepted formats: `PDF`, `DOCX`, `JPEG`, `JPG` and `PNG`. All files are converted to PDF upon upload.'
          format: binary
          type: string
        nature:
          description: 'Can take two values: `signable_document` or `attachment`. Files in `JPEG`, `JPG`, and `PNG` format can only be of `attachment` nature.'
          enum:
          - attachment
          - signable_document
          type: string
        insert_after_id:
          description: Insert just after the position of the specified document id.
          example: 8b6ed2f3-244f-487a-baa1-bbe4f51c8744
          format: uuid
          nullable: true
          type: string
        password:
          example: MyPa$$word
          type: string
        name:
          description: The document name. If not set, will use the uploaded document name. This value should contain any characters except "\", "/" and can\'t start and finish with a space.
          example: file1
          maxLength: 128
          minLength: 1
          pattern: ^(?!\s)[^\/\\]+(?<!\s)$
          type: string
        initials:
          allOf:
          - $ref: '#/components/schemas/InitialsArea'
          nullable: true
          type: object
        parse_anchors:
          default: false
          description: If true, the system will parse the document exclusively for Signature-type Smart Anchors and automatically generate the required fields.
          example: true
          nullable: true
          type: boolean
        excluded_approvers:
          $ref: '#/components/schemas/DocumentExcludedApprovers'
        excluded_signers:
          $ref: '#/components/schemas/DocumentExcludedSigners'
      required:
      - file
      - nature
      type: object
    InitialsArea:
      properties:
        alignment:
          description: Alignment of the Initials on the document. The `left`, `right` and `center` options are aligned on top of the page by default.
          enum:
          - left
          - right
          - center
          - top-left
          - top-right
          - top-center
          - bottom-left
          - bottom-right
          - bottom-center
          type: string
        y:
          description: Offset of the initials from the edge of the page (in pixels). The offset is from the top or bottom of the page, depending on what has been defined in the `alignment` attribute.
          example: 10
          minimum: 0
          type: integer
      required:
      - alignment
      - y
      title: InitialsArea
      type: object
    MethodNotAllowed:
      properties:
        message:
          type: string
      required:
      - message
      title: MethodNotAllowed
      type: object
    Document:
      description: Document to attach to a Signature Request
      properties:
        id:
          example: 89120884-d29a-4b1a-ac7b-a9e73a872796
          format: uuid
          type: string
        filename:
          maxLength: 255
          minLength: 1
          type: string
        nature:
          enum:
          - attachment
          - signable_document
          type: string
        content_type:
          example: application/pdf
          type: string
        sha256:
          description: Sha256 checksum
          type: string
        is_protected:
          type: boolean
        is_signed:
          type: boolean
        created_at:
          example: '2024-01-18T22:59:00Z'
          format: date-time
          type: string
        total_pages:
          description: Number of pages for signable document
          minimum: 1
          nullable: true
          type: integer
        is_locked:
          description: If protected by password and not yet unlocked
          type: boolean
        initials:
          $ref: '#/components/schemas/Document_initials'
        total_anchors:
          description: Number of parsed anchors from the document.
          type: integer
        excluded_approvers:
          description: 'List of Approver IDs who cannot see this Document.

            '
          items:
            format: uuid
            type: string
          type: array
        excluded_signers:
          description: 'List of Signer IDs who cannot see this Document.

            '
          items:
            format: uuid
            type: string
          type: array
      required:
      - content_type
      - created_at
      - excluded_approvers
      - excluded_signers
      - filename
      - id
      - initials
      - is_locked
      - is_protected
      - is_signed
      - nature
      - sha256
      - total_anchors
      - total_pages
      title: Document
      type: object
    Document_initials:
      nullable: true
      properties:
        alignment:
          description: Alignment of the initials on the document’s pages.
          enum:
          - left
          - center
          - right
          type: string
        y:
          description: Y-axis position of the initials on the first page of the document.
          minimum: 0
          type: integer
        per_page:
          items:
            $ref: '#/components/schemas/Document_initials_per_page_inner'
          type: array
      required:
      - alignment
      - per_page
      - y
      type: object
    BadRequestResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: BadRequestResponse
      type: object
    ForbiddenResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: ForbiddenResponse
      type: object
    UnauthorizedResponse:
      properties:
        type:
          type: string
        detail:
          type: string
      required:
      - detail
      - type
      title: UnauthorizedResponse
      type: object
    DocumentExcludedSigners:
      description: 'List of Signer IDs who cannot see this Document. When omitted, all Signers can see it (default). Requires the document_visibility feature to be enabled on the organization.

        '
      example:
      - 550e8400-e29b-41d4-a716-446655440000
      - 6ba7b810-9dad-11d1-80b4-00c04fd430c8
      items:
        format: uuid
        type: string
      type: array
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http