Conga Approval API

openapi: 3.2.0
info:
  title: Conga Sign Approval API
  version: 1.0.0
servers:
- url: https://rls.congacloud.com/api/sign
security:
- JWT: []
tags:
- name: Approval
paths:
  /v1/cs-packages/{packageId}/documents/{documentId}/approvals:
    post:
      tags:
      - Approval
      summary: Create an approval
      description: 'Creates a new approval for a package or document.

        Note that text anchor extraction cannot be used in this API call.'
      operationId: Approval_CreateApproval
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      requestBody:
        x-name: approval
        description: The approval object to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Approval'
        required: true
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    put:
      tags:
      - Approval
      summary: Update an approval
      description: Updates the existing approval requests on a package or a document.
      operationId: Approval_UpdateApprovals
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      requestBody:
        x-name: approvals
        description: The list of approvals to update.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Approval'
        required: true
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOfApproval'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
  /v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}:
    delete:
      tags:
      - Approval
      summary: Delete an existing approval
      description: Deletes a specific approval that already exists for a package or document.
      operationId: Approval_DeleteApproval
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    get:
      tags:
      - Approval
      summary: Retrieve an approval
      description: Retrieves an approval for the identified package or document.
      operationId: Approval_GetApproval
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package identifier.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document identifier.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    put:
      tags:
      - Approval
      summary: Update an approval
      description: Updates a specific approval created for a package or a document.
      operationId: Approval_UpdateApproval
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      requestBody:
        x-name: approval
        description: The approval object to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Approval'
        required: true
        x-position: 4
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Approval'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
  /v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields:
    post:
      tags:
      - Approval
      summary: Create a new field with an autogenerated name related to an existing approval
      description: Creates a new field for an existing approval. The new field is created with an autogenerated name.
      operationId: Approval_CreateApprovalField
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      requestBody:
        x-name: field
        description: The field object to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
        required: true
        x-position: 4
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
  /v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}:
    post:
      tags:
      - Approval
      summary: Create a field related to an approval with a specific field ID
      description: 'Creates a new field that can then be added to an existing approval.


        Note: There is a known behavior where this endpoint may function similarly to PUT (update).

        This may be legacy behavior on OneSpan''s side. Use with caution and verify behavior.'
      operationId: Approval_CreateApprovalFieldById
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      - name: fieldId
        in: path
        required: true
        description: The unique field id.
        schema:
          type: string
        x-position: 4
      requestBody:
        x-name: field
        description: The field object to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
        required: true
        x-position: 5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    delete:
      tags:
      - Approval
      summary: Delete a field from an approval.
      description: Deletes a field added to an existing approval.
      operationId: Approval_DeleteFieldById
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      - name: fieldId
        in: path
        required: true
        description: The unique field id.
        schema:
          type: string
        x-position: 4
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    get:
      tags:
      - Approval
      summary: Retrieve an approval field
      description: Retrieves a field that exists on an already created approval.
      operationId: Approval_GetApprovalField
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      - name: fieldId
        in: path
        required: true
        description: The unique field id.
        schema:
          type: string
        x-position: 4
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    put:
      tags:
      - Approval
      summary: Update a field related to an approval
      description: 'Updates an existing field related to an existing approval.

        Note that the JSON Field ID will be ignored and replaced by the one from the query parameter.'
      operationId: Approval_UpdateApprovalField
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      - name: fieldId
        in: path
        required: true
        description: The unique field id.
        schema:
          type: string
        x-position: 4
      requestBody:
        x-name: field
        description: The field object to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Field'
        required: true
        x-position: 5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
  /v1/cs-packages/{packageId}/documents/{documentId}/approvals/{approvalId}/fields/{fieldId}/conditionalFields:
    put:
      tags:
      - Approval
      summary: Updates the conditions for a given approval field
      description: "Updates the conditions for a given field. In addition to the array of conditions, \nthe payload should contain all Field properties. The value of the field is replaced by this payload.\n\nConditional fields allow you to show/hide or enable/disable fields based on the values \nof other fields in the document.\n\nExample use case: Show \"Company Name\" field only if user selects \"Business\" in the \"Account Type\" field."
      operationId: Approval_UpdateConditionalFields
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: approvalId
        in: path
        required: true
        description: The unique approval id.
        schema:
          type: string
        x-position: 3
      - name: fieldId
        in: path
        required: true
        description: The unique field id.
        schema:
          type: string
        x-position: 4
      requestBody:
        x-name: conditionalField
        description: The conditional field object containing conditions and field properties.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConditionalField'
        required: true
        x-position: 5
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConditionalField'
        '400':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
  /v1/cs-packages/{packageId}/documents/{documentId}/signers/{signerId}/approvals:
    get:
      tags:
      - Approval
      summary: Retrieve all signable approvals
      description: Retrieves all approvals that are eligible for signature.
      operationId: Approval_GetSignerApproval
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: documentId
        in: path
        required: true
        description: The unique document id.
        schema:
          type: string
        x-position: 2
      - name: signerId
        in: path
        required: true
        description: The unique signer id.
        schema:
          type: string
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOfApproval'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '403':
          description: Access Denied Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
components:
  schemas:
    Error2:
      type: object
      description: Object representing an error condition
      additionalProperties: false
      properties:
        code:
          type:
          - integer
          - 'null'
          description: The error code
          format: int32
        entity:
          description: The Microsoft Dynamics entity
          oneOf:
          - $ref: '#/components/schemas/Entity'
        message:
          type: string
          description: The error message
        messageKey:
          type: string
          description: The error message key
        name:
          type: string
          description: The error name
        technical:
          type: string
          description: Technical information about the error
    ResultOfApproval:
      type: object
      description: Object used to manage OneSpan list types
      additionalProperties: false
      properties:
        count:
          type: integer
          description: Count
          format: int32
        results:
          type: array
          description: Results
          items:
            $ref: '#/components/schemas/Approval'
    Approval:
      type: object
      description: Signing Approval object.
      additionalProperties: false
      properties:
        accepted:
          type:
          - string
          - 'null'
          description: Date of approval acceptance.
          format: date-time
        data:
          type: object
          description: Additional approval ata properties.
          additionalProperties: {}
        fields:
          type: array
          description: Approval Signature/Input fields.
          items:
            $ref: '#/components/schemas/Field'
        id:
          type: string
          description: The unique approval Id.
        name:
          type: string
          description: The unique approval name.
        role:
          type: string
          description: The approval role name.
        signed:
          type:
          - string
          - 'null'
          description: The approval signed date.
          format: date-time
        optional:
          type: boolean
          description: Check if for optional information.
        enforceCaptureSignature:
          type: boolean
          description: Check if required on Capture Signature
        disabled:
          type: boolean
          description: Check if disabled for approval.
        fromFile:
          type: boolean
          description: Check if signature is uploaded From File.
        fromFileData:
          type: object
          description: Additional approval From File data properties.
          additionalProperties: {}
    FieldCondition:
      type: object
      description: Object to manage field conditions
      additionalProperties: false
      properties:
        id:
          type: string
          description: The id of the field condition
        condition:
          type: string
          description: The condition that determines if action is needed
        action:
          type: string
          description: The action to take when the condition is true
    FieldValidation:
      type: object
      description: Field validation object
      additionalProperties: false
      properties:
        enum:
          type: array
          items:
            type: string
        errorCode:
          type:
          - integer
          - 'null'
          description: Field validation error code.
          format: int32
        errorMessage:
          type: string
          description: "Field validation error message.\n            "
        maxLength:
          type:
          - integer
          - 'null'
          description: Field validation maximum length.
          format: int32
        minLength:
          type:
          - integer
          - 'null'
          description: Field validation minimum length.
          format: int32
        pattern:
          type: string
          description: Pattern
        required:
          type: boolean
          description: Determines if field is required
        group:
          type: string
          description: Field validation group.
        minimumRequired:
          type:
          - integer
          - 'null'
          description: Minimum Required (Grouped Checkboxes)
          format: int32
    ExtractAnchor:
      type: object
      description: Text extraction anchor object.
      additionalProperties: false
      properties:
        anchorPoint:
          description: Which corner of the specified character to use as the base for calculating position
          oneOf:
          - $ref: '#/components/schemas/AnchorPointType'
        characterIndex:
          type: integer
          description: The index of the character within the Anchor Text that will be used to calculate position
          format: int32
        height:
          type: integer
          description: The height of the field position to be calculated
          format: int32
        index:
          type: integer
          description: The "occurrence" of the string. For example, if index = 2, the software will skip the first two occurrences of Anchor Text, and use the third occurrence to calculate position.
          format: int32
        leftOffset:
          type: integer
          description: An absolute offset applied to the final x value
          format: int32
        text:
          type: string
          description: The exact string that will be searched for in the uploaded document
        topOffset:
          type: integer
          description: An absolute offset applied to the final y value
          format: int32
        width:
          type: integer
          description: The width of the field position to be calculated
          format: int32
    FieldType:
      type: string
      description: ''
      x-enumNames:
      - SIGNATURE
      - INPUT
      - IMAGE
      enum:
      - SIGNATURE
      - INPUT
      - IMAGE
    Entity:
      type: object
      description: Object used to manage entities from Microsoft Dynamics
      additionalProperties: false
      properties:
        data:
          type: object
          description: Custom data for the entity
          additionalProperties: {}
        id:
          type: string
          description: Unique id of the entity
        name:
          type: string
          description: Name of the entity
    ConditionalField:
      allOf:
      - $ref: '#/components/schemas/Field'
      - type: object
        description: Conditional fields
        additionalProperties: false
        properties:
          conditions:
            type: array
            description: List of conditions for a field
            items:
              $ref: '#/components/schemas/FieldCondition'
    AnchorPointType:
      type: string
      description: ''
      x-enumNames:
      - TOPLEFT
      - BOTTOMLEFT
      - TOPRIGHT
      - BOTTOMRIGHT
      enum:
      - TOPLEFT
   

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/conga/refs/heads/main/openapi/conga-approval-api-openapi.yml