# Provenance: modeled-from-docs (2026-07-17).
# Digio does not publish a downloadable first-party OpenAPI/Swagger file. This
# document was MODELED from Digio's public product documentation at
# https://documentation.digio.in/ and widely-published integration guides.
# Hosts are live-verified: production https://api.digio.in (HTTP 404 at root =
# API host, AWS/Amazon RSA TLS) and sandbox https://ext.digio.in (HTTP 200).
# Authentication is HTTP Basic using Base64(client_id:client_secret), confirmed
# across Digio docs and third-party integration references. Exact endpoint
# paths, versions, and request/response schemas should be re-verified against
# documentation.digio.in before production use.
openapi: 3.0.3
info:
  title: Digio API
  description: >-
    Digio is an India-based digital trust and paperwork automation platform
    offering legally-valid Aadhaar/OTP eSign, eStamping, KYC (CKYC, KRA,
    DigiLocker, offline Aadhaar, Video KYC), eNACH/NACH eMandates, UPI Autopay,
    AML/CFT screening, and document/agreement management over a REST API.
    All requests use HTTPS with HTTP Basic authentication
    (Base64 of client_id:client_secret). Asynchronous status updates are
    delivered via HTTP webhooks; there is no WebSocket surface.
  version: '1.0'
  contact:
    name: Digio Developer Support
    url: https://documentation.digio.in/
    email: tech@digio.in
  termsOfService: https://www.digio.in/
servers:
  - url: https://api.digio.in
    description: Production
  - url: https://ext.digio.in
    description: Sandbox / Test
security:
  - basicAuth: []
tags:
  - name: eSign
    description: DigiSign - Aadhaar and OTP based legally-valid electronic signatures.
  - name: eMandate
    description: DigiCollect - eNACH / NACH electronic mandates for recurring debit.
  - name: KYC
    description: DigiKYC - identity verification via CKYC, KRA, DigiLocker, and offline Aadhaar.
  - name: Documents
    description: DigiDocs - template-based document and agreement creation with eStamp.
paths:
  /v2/client/document/upload:
    post:
      operationId: uploadDocumentForSign
      tags:
        - eSign
      summary: Upload a document and create an eSign request
      description: >-
        Uploads a PDF file and creates a signature request for one or more
        signers (identified by a single email or phone number). Returns a
        document id prefixed with DID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadDocumentRequest'
      responses:
        '200':
          description: Sign request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/client/document/uploadpdf:
    post:
      operationId: uploadPdfForSign
      tags:
        - eSign
      summary: Create an eSign request from a base64 PDF
      description: >-
        Creates a signature request from a base64-encoded PDF payload rather
        than a multipart file upload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadPdfRequest'
      responses:
        '200':
          description: Sign request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/client/document/{document_id}:
    get:
      operationId: getDocument
      tags:
        - eSign
      summary: Get eSign request details
      description: Retrieves the current status and signer details of a signature request.
      parameters:
        - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          description: Document details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/client/document/download/{document_id}:
    get:
      operationId: downloadSignedDocument
      tags:
        - eSign
      summary: Download a signed document
      description: Downloads the completed, signed PDF for a signature request.
      parameters:
        - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          description: Signed PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/client/template/multi_templates/create_sign_request:
    post:
      operationId: createSignRequestFromTemplate
      tags:
        - Documents
      summary: Create a sign request from a template
      description: >-
        Generates a document from a pre-configured DigiDocs template (with
        optional eStamp) and creates an eSign request in one call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplateSignRequest'
      responses:
        '200':
          description: Sign request created from template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/client/mandate/create:
    post:
      operationId: createMandate
      tags:
        - eMandate
      summary: Create an eNACH / NACH mandate
      description: >-
        Creates an electronic mandate (eNACH via NPCI, UPI Autopay, or physical
        NACH) authorizing recurring debit from a customer bank account. Returns
        a mandate id prefixed with NACH/MANDATE.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMandateRequest'
      responses:
        '200':
          description: Mandate created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mandate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/client/mandate/{mandate_id}:
    get:
      operationId: getMandate
      tags:
        - eMandate
      summary: Get mandate details
      description: Retrieves the status and details of an eNACH / NACH mandate.
      parameters:
        - $ref: '#/components/parameters/MandateId'
      responses:
        '200':
          description: Mandate details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mandate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/client/mandate/{mandate_id}/cancel:
    post:
      operationId: cancelMandate
      tags:
        - eMandate
      summary: Cancel a mandate
      description: Cancels an active eNACH / NACH mandate.
      parameters:
        - $ref: '#/components/parameters/MandateId'
      responses:
        '200':
          description: Mandate cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mandate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /client/kyc/v2/request/with_template:
    post:
      operationId: createKycRequest
      tags:
        - KYC
      summary: Create a KYC request with a template
      description: >-
        Initiates a KYC verification workflow using a pre-configured DigiKYC
        template (Aadhaar offline, DigiLocker, ID proof, CKYC, KRA, Video KYC).
        Returns a request id prefixed with KID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KycRequest'
      responses:
        '200':
          description: KYC request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /client/kyc/v2/{request_id}/response:
    get:
      operationId: getKycResponse
      tags:
        - KYC
      summary: Get KYC request response
      description: >-
        Fetches the collected identity data, extracted fields, and verification
        result for a completed KYC request.
      parameters:
        - name: request_id
          in: path
          required: true
          description: KYC request identifier (KID...).
          schema:
            type: string
      responses:
        '200':
          description: KYC response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KycResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. Send the header
        Authorization: Basic Base64(client_id:client_secret).
  parameters:
    DocumentId:
      name: document_id
      in: path
      required: true
      description: Signature request identifier (DID...).
      schema:
        type: string
    MandateId:
      name: mandate_id
      in: path
      required: true
      description: Mandate identifier.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid Basic authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Signer:
      type: object
      properties:
        identifier:
          type: string
          description: A single signer identifier - either an email address or a phone number.
        name:
          type: string
        reason:
          type: string
          description: Reason for signing.
        sign_type:
          type: string
          description: Signature type.
          enum:
            - aadhaar
            - electronic
            - dsc
      required:
        - identifier
    UploadDocumentRequest:
      type: object
      properties:
        signers:
          type: array
          items:
            $ref: '#/components/schemas/Signer'
        expire_in_days:
          type: integer
        display_on_page:
          type: string
          enum:
            - first
            - last
            - all
            - custom
        notify_signers:
          type: boolean
        send_sign_link:
          type: boolean
        file_name:
          type: string
        file_data:
          type: string
          description: Base64-encoded PDF content.
      required:
        - signers
        - file_name
    UploadPdfRequest:
      allOf:
        - $ref: '#/components/schemas/UploadDocumentRequest'
    TemplateSignRequest:
      type: object
      properties:
        template_values:
          type: object
          additionalProperties: true
        template_id:
          type: string
        signers:
          type: array
          items:
            $ref: '#/components/schemas/Signer'
      required:
        - template_id
        - signers
    SignDocument:
      type: object
      properties:
        id:
          type: string
          description: Document identifier (DID...).
        is_agreement:
          type: boolean
        agreement_type:
          type: string
        signing_parties:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              identifier:
                type: string
              status:
                type: string
                enum:
                  - requested
                  - signed
                  - expired
        file_name:
          type: string
        created_at:
          type: string
          format: date-time
        agreement_status:
          type: string
          enum:
            - requested
            - completed
            - expired
    CreateMandateRequest:
      type: object
      properties:
        customer_identifier:
          type: string
          description: Customer email or phone number.
        auth_mode:
          type: string
          description: Mandate authentication mode.
          enum:
            - netbanking
            - debit_card
            - aadhaar
            - upi
        mandate_type:
          type: string
          enum:
            - create
            - modify
            - cancel
        maximum_amount:
          type: number
        first_collection_date:
          type: string
          format: date
        final_collection_date:
          type: string
          format: date
        frequency:
          type: string
          enum:
            - Adhoc
            - Monthly
            - Quarterly
            - Yearly
        destination_bank_id:
          type: string
      required:
        - customer_identifier
        - maximum_amount
    Mandate:
      type: object
      properties:
        mandate_id:
          type: string
        state:
          type: string
          enum:
            - register_initiated
            - register_success
            - register_failed
            - cancelled
        npci_txn_id:
          type: string
        umrn:
          type: string
          description: Unique Mandate Reference Number issued by NPCI.
        maximum_amount:
          type: number
        created_at:
          type: string
          format: date-time
    KycRequest:
      type: object
      properties:
        customer_identifier:
          type: string
          description: Customer email or phone number.
        customer_name:
          type: string
        template_name:
          type: string
          description: DigiKYC workflow template name.
        notify_customer:
          type: boolean
        generate_access_token:
          type: boolean
      required:
        - customer_identifier
        - template_name
    KycResponse:
      type: object
      properties:
        id:
          type: string
          description: KYC request identifier (KID...).
        status:
          type: string
          enum:
            - requested
            - approval_pending
            - approved
            - rejected
        customer_identifier:
          type: string
        actions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              status:
                type: string
              details:
                type: object
                additionalProperties: true
        created_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
        details:
          type: string