openapi.yaml

openapi: 3.0.0
info:
  version: 1.0.0
  title: Lumin Sign Api Reference
  description: |
    The Lumin Sign API Reference supplies a wide range of eSignature tools for your application.

    Some useful links:
    - [The document repository](https://github.com/luminpdf/luminsign-docs)
    - [The source API definition for the Lumin Sign API](https://github.com/luminpdf/luminsign-docs/blob/main/openapi.yaml)
    - [Authentication for using API](/docs/api/authentication/)
  contact:
    name: API Support
    email: integration@luminpdf.com
    url: https://help.luminpdf.com
servers:
  - url: https://api.luminpdf.com/v1
    description: Production server
  - url: https://api-sandbox.luminpdf.com/v1
    description: Sandbox server
tags:
  - name: Signature Request
    description: Everything about Signature Request
  - name: User
    description: Everything about User
paths:
  /signature_request/{signature_request_id}:
    get:
      summary: Get Signature Request
      description: Get Signature Request by id.
      security:
        - ApiKey: []
      tags:
        - Signature Request
      parameters:
        - in: path
          name: signature_request_id
          schema:
            type: string
          required: true
          description: ID of the Signature Request to get
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: object
                required:
                  - signature_request
                properties:
                  signature_request:
                    description: Contains information about a Signature Request.
                    $ref: '#/components/schemas/SignatureRequest'
        '4xx':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /signature_request/send:
    post:
      summary: Send Signature Request
      description: Creates and sends a new Signature Request with the submitted documents.
      security:
        - ApiKey: []
      tags:
        - Signature Request
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignatureRequestDTO'
      responses:
        '201':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: object
                required:
                  - signature_request
                properties:
                  signature_request:
                    description: Contains information about a Signature Request.
                    required:
                      - signature_request_id
                      - created_at
                      - status
                    properties:
                      signature_request_id:
                        type: string
                        description: The unique identifier for the Signature Request.
                      created_at:
                        type: string
                        description: The time the Signature Request was created.
                      status:
                        type: string
                        description: The status of the Signature Request.
                        enum:
                          - WAITING_FOR_PROCESSING
                          - FAILED
        '4xx':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /signature_request/cancel/{signature_request_id}:
    put:
      summary: Cancel Signature Request
      description: Cancel Signature Request by id.
      security:
        - ApiKey: []
      tags:
        - Signature Request
      parameters:
        - in: path
          name: signature_request_id
          schema:
            type: string
          required: true
          description: ID of the Signature Request to cancel
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  signature_request_id:
                    type: string
                    description: The unique identifier for the Signature Request.
                  status:
                    type: string
                    description: The status of the Signature Request.
                    enum:
                      - CANCELLED
        '4xx':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /signature_request/files_as_file_url/{signature_request_id}:
    get:
      summary: Download File as File URL
      description: Obtain the file of the Signature Request by id as a file URL. Returns a JSON object with a url to the file
      security:
        - ApiKey: []
      tags:
        - Signature Request
      parameters:
        - in: path
          name: signature_request_id
          schema:
            type: string
          required: true
          description: ID of the Signature Request to get
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_url:
                    type: string
                    description: The url of the file, which will be downloaded and signed.
                  expires_at:
                    type: integer
                    format: unix-epoch
                    description: When the file url will expire. This is a unix epoch timestamp (miliseconds).
        '4xx':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /signature_request/files/{signature_request_id}:
    get:
      summary: Download File
      description: Obtain the file of the Signature Request by id. Returns a PDF file.
      security:
        - ApiKey: []
      tags:
        - Signature Request
      parameters:
        - in: path
          name: signature_request_id
          schema:
            type: string
          required: true
          description: ID of the Signature Request to get
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '4xx':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /user/info:
    get:
      summary: Get User Information
      description: Get information of current user by API Key
      security:
        - ApiKey: []
      tags:
        - User
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                type: object
                required:
                  - user
                properties:
                  user:
                    description: Contains information about a User.
                    $ref: '#/components/schemas/User'
        '4xx':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-API-KEY
      in: header
  schemas:
    Signer:
      type: object
      required:
        - email_address
        - name
      properties:
        email_address:
          type: string
        name:
          type: string
        group:
          type: number
          description: The signing order of signer for the Signature Request with `signing_type` is `ORDER`.
    Viewer:
      type: object
      required:
        - email_address
        - name
      properties:
        email_address:
          type: string
        name:
          type: string
    SignatureRequest:
      type: object
      required:
        - signature_request_id
        - title
        - created_at
        - expires_at
        - details_url
        - status
        - signers
        - signing_type
      properties:
        signature_request_id:
          type: string
          description: The unique identifier for the Signature Request.
        title:
          type: string
          description: The title of the Signature Request.
        created_at:
          type: string
          description: The time the Signature Request was created.
        updated_at:
          type: string
          description: The time the Signature Request was last updated.
        expires_at:
          type: string
          description: The time the Signature Request will expire.
        details_url:
          type: string
          description: The url to view the Signature Request in the browser.
        status:
          type: string
          description: The status of the Signature Request.
          enum:
            - NEED_TO_SIGN
            - WAITING_FOR_OTHERS
            - APPROVED
            - REJECTED
            - WAITING_FOR_PROCESSING
            - FAILED
            - CANCELLED
        reason:
          type: string
          description: The reason for the status FAILED or REJECTED of the Signature Request.
        signing_type:
          type: string
          description: The type of signing for the Signature Request.
          enum:
            - SAME_TIME
            - ORDER
        signers:
          type: array
          items:
            required:
              - email_address
              - name
              - is_approved
              - status
            allOf:
              - $ref: '#/components/schemas/Signer'
              - properties:
                  is_approved:
                    type: boolean
                    description: Whether the Signer has approved the Signature Request.
                  status:
                    type: string
                    description: The status of the Signer.
                    enum:
                      - NEED_TO_SIGN
                      - APPROVED
                      - REJECTED
                      - WAITING_FOR_OTHERS
          description: The Signers of the Signature Request.
    User:
      type: object
      required:
        - email
        - id
        - name
      properties:
        id:
          type: string
        email:
          type: string
        name:
          type: string
    SignatureRequestDTO:
      type: object
      required:
        - signers
        - title
        - expires_at
      properties:
        file_url:
          type: string
          description: The URL of a single file to be downloaded and signed. This field is mutually exclusive with `file`, `files`, and `file_urls`. Only one of these fields should be provided in the request.
        file:
          type: string
          format: binary
          description:  A single uploaded file to be sent for signature. This field is mutually exclusive with `file_url`, `files`, and `file_urls`. Only one of these fields should be provided in the request.
        file_urls:
          type: array
          description: An array of URLs of files to be downloaded and signed. This field is mutually exclusive with `file`, `files`, and `file_url`. Only one of these fields should be provided in the request.
          items:
            type: string
        files:
          type: array
          description: An array of uploaded files to be sent for signature. This field is mutually exclusive with `file`, `file_url`, and `file_urls`. Only one of these fields should be provided in the request.
          items:
            type: binary
        signers:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Signer'
              - properties:
                  group:
                    type: number
                    description: |
                      The signing order of signer for the Signature Request with `signing_type` is `ORDER`. Required if `signing_type` is `ORDER`.

                      Only signers in `1st Signers` group will receive email/notification, signers in subsequent groups will receive email/notification when all signers in previous group has signed.

                      Group starts incrementing at 1.

                       The default value for group always is 1 if `signing_type` is `SAME_TIME.`
          description: Add Signers to your Signature Request.
        viewers:
          type: array
          items:
            $ref: '#/components/schemas/Viewer'
          description: Add Viewers to your Signature Request.
        title:
          type: string
          minLength: 1
          maxLength: 255
          description: The title you want to give the Signature Request.
        expires_at:
          type: integer
          format: unix-epoch
          description: When the Signature Request will expire. This is a unix epoch timestamp (miliseconds). Should be later than today.
        use_text_tags:
          type: boolean
          description: Set to `true` to enable Text Tag parsing in your document. Your Text Tags will be converted into UI components for the user to interact with. Defaults to `false`.
        signing_type:
          type: string
          description: The signing order for the Signature Request. Defaults to `SAME_TIME`.
          enum:
            - SAME_TIME
            - ORDER
        custom_email:
          type: object
          description: Custom email content for the email sent to signers.
          properties:
            sender_email:
              type: string
              description: The email address of the sender.
            subject_name:
              type: string
              description: The subject of the email.
            title:
              type: string
              description: The title of the email.
      example:
        file_url: https://lumin-assets-production.s3.us-east-1.amazonaws.com/api-demo/Direct+Debit+form.pdf
        signers:
          - email_address: nhuttm@luminpdf.com
            name: Nhut Tran
            group: 1
          - email_address: tuyen_ptt@luminpdf.com
            name: Tuyen Phan
            group: 1
          - email_address: son_lt@luminpdf.com
            name: Thi Son
            group: 2
        viewers:
          - email_address: hau_le@luminpdf.com
            name: Hau Le
          - email_address: giang_pl@luminpdf.com
            name: Giang Phan
          - email_address: phap_hl@luminpdf.com
            name: Phap Hello

        title: My first request signing document
        expires_at: 1727510980694
        use_text_tags: false
        signing_type: ORDER
    Error:
      type: object
      required:
        - error_code
        - error_message
      properties:
        error_code:
          type: string
        error_message:
          type: string