Conga Role API

openapi: 3.2.0
info:
  title: Conga Role API
  version: '1.0'
  description: 'Operations tagged Role across 2 of this provider''s published API definitions: conga-conga-sign.json, conga-user-management.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rls.congacloud.com/api/sign
- url: https://rls.congacloud.com
tags:
- name: Role
paths:
  /v1/cs-packages/{packageId}/groups:
    post:
      tags:
      - Role
      summary: Adds a new ad hoc group to a transaction
      description: 'Adds a new ad hoc group and its members to an existing transaction.


        An ad hoc group allows multiple signers to be grouped together, where only one member

        needs to sign on behalf of the entire group.


        The request body must be an array of Role objects:

        1. Individual member roles (regular signers) - these become potential group members

        2. The ad hoc group role with a special signer that has:

        - signerType: "AD_HOC_GROUP_SIGNER"

        - group.members: Array referencing the member role IDs


        Example structure:

        [

        {

        "signers": [{ "firstName": "John", "lastName": "Doe", "email": "john@example.com" }],

        "id": "member-role-id-1"

        },

        {

        "signers": [{ "firstName": "Jane", "lastName": "Smith", "email": "jane@example.com" }],

        "id": "member-role-id-2"

        },

        {

        "id": "ad-hoc-group-role-id",

        "signers": [{

        "firstName": "Legal Review Group",

        "signerType": "AD_HOC_GROUP_SIGNER",

        "group": {

        "members": [

        { "userId": "member-role-id-1", "memberType": "AD_HOC_GROUP_MEMBER" },

        { "userId": "member-role-id-2", "memberType": "SIGNER" }

        ]

        }

        }]

        }

        ]'
      operationId: Role_CreateAdHocGroup
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: roles
        description: 'Array of Role objects: member roles followed by the ad hoc group role.'
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Role'
        required: true
        x-position: 2
      responses:
        '200':
          description: OK - Ad hoc group created successfully
        '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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    servers:
    - url: https://rls.congacloud.com/api/sign
  /v1/cs-packages/{packageId}/groups/{roleId}:
    delete:
      tags:
      - Role
      summary: Deletes a specified ad hoc group
      description: 'Deletes a specified ad hoc group from a transaction.


        This will remove:

        - The ad hoc group role

        - All member roles that were created for this group


        Note: If member roles are used elsewhere in the package, they may not be deleted.'
      operationId: Role_DeleteAdHocGroup
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: roleId
        in: path
        required: true
        description: The unique role id within the package.
        schema:
          type: string
        x-position: 2
      responses:
        '200':
          description: OK - Group deleted successfully
        '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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found - Group does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    put:
      tags:
      - Role
      summary: Updates a transaction's existing ad hoc group
      description: 'Updates an existing ad hoc group, for a specified transaction, including any changes

        to the group''s members.


        The request body structure is the same as creation:

        - Array of member Role objects (existing or new members)

        - The ad hoc group Role object with updated configuration


        You can:

        - Add new members by including their roles in the array

        - Remove members by excluding them from the group.members array

        - Update the group name via the signer''s firstName

        - Modify member types (AD_HOC_GROUP_MEMBER vs SIGNER)


        Member types:

        - AD_HOC_GROUP_MEMBER: Must sign if selected

        - SIGNER: Optional member (can be selected to sign)'
      operationId: Role_UpdateAdHocGroup
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: roleId
        in: path
        required: true
        description: The unique role id within the package.
        schema:
          type: string
        x-position: 2
      requestBody:
        x-name: groupRoles
        description: Array of Role objects with updated member roles and group configuration.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/Role'
        required: true
        x-position: 3
      responses:
        '200':
          description: OK - Ad hoc group updated successfully
        '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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: Not Found - Group does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    servers:
    - url: https://rls.congacloud.com/api/sign
  /v1/cs-packages/{packageId}/roles:
    post:
      tags:
      - Role
      summary: Add new role
      description: Adds a new role to an existing package.
      operationId: Role_CreateRole
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: role
        description: The role to add.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
        x-position: 2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    get:
      tags:
      - Role
      summary: Retrieve all package roles
      description: Retrieves all roles for the package.
      operationId: Role_ListRoles
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOfRole'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    put:
      tags:
      - Role
      summary: Reorder package roles
      description: Reorders the roles in a specified package.
      operationId: Role_ReorderRoles
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: roleReordering
        description: List of role reordering specifications.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RoleReordering'
        required: true
        x-position: 2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultOfRole'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    servers:
    - url: https://rls.congacloud.com/api/sign
  /v1/cs-packages/{packageId}/roles/{roleId}:
    delete:
      tags:
      - Role
      summary: Delete a role
      description: Deletes a specified role.
      operationId: Role_DeleteRole
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: roleId
        in: path
        required: true
        description: The unique role id within the package.
        schema:
          type: string
        x-position: 2
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    get:
      tags:
      - Role
      summary: Retrieve a role
      description: Retrieves a single role associated with a package.
      operationId: Role_GetRole
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: roleId
        in: path
        required: true
        description: The unique role id within the package.
        schema:
          type: string
        x-position: 2
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    put:
      tags:
      - Role
      summary: Update roles in the package
      description: Updates a single Role by overriding its existing values with those in the JSON payload.
      operationId: Role_UpdateRole
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: roleId
        in: path
        required: true
        description: The unique role id within the package.
        schema:
          type: string
        x-position: 2
      requestBody:
        x-name: role
        description: The updated role data.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    servers:
    - url: https://rls.congacloud.com/api/sign
  /v1/cs-packages/{packageId}/roles/{roleId}/unlock:
    post:
      tags:
      - Role
      summary: Unlock a role
      description: Unlocks a specified role.
      operationId: Role_UnlockRole
      parameters:
      - name: packageId
        in: path
        required: true
        description: The unique package id.
        schema:
          type: string
        x-position: 1
      - name: roleId
        in: path
        required: true
        description: The unique role id within the package.
        schema:
          type: string
        x-position: 2
      requestBody:
        x-name: role
        description: The role to unlock.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Role'
        required: true
        x-position: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '401':
          description: Not Authorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
        '500':
          description: Unexpected Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error2'
      security:
      - JWT: []
    servers:
    - url: https://rls.congacloud.com/api/sign
  /api/user-management/v1/runtime/roles:
    get:
      tags:
      - Role
      summary: Get all roles
      description: Returns all roles that meet the criteria.
      parameters:
      - name: criteria
        in: query
        description: 'Search criteria for the roles. **For example**: IsDeleted != ''true''.<p>**Note**: The criteria field (in this case, IsDeleted) should be indexed.</p>'
        schema:
          type: string
      - name: sortField
        in: query
        description: 'Field name for sorting. **For example**: Name.<p>**Note**: The sort field (in this case, Name) should be indexed or sortable.</p>'
        schema:
          type: string
      - name: sortDirection
        in: query
        description: 'Sort direction (Ascending or Descending) of the data. For example: ASC or DESC<p>**Note**: The default sort order is **DESC** if the sort field parameter is specified.</p>'
        schema:
          type: string
      - name: pageSize
        in: query
        description: The number of records to display on each page.
        schema:
          type: integer
          format: int32
      - name: pageNumber
        in: query
        description: The page number of the result set to view.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringObjectDictionaryListAPIResponse'
              example:
                Success: true
                RecordCount: 2
                Data:
                - Description: GeneralUserRole
                  Id: a7e0eb7f-8c43-429e-a5a4-6a1a6dd533ac
                  PermissionGroups: GlobalScopePermissionGroup
                  Name: GeneralUser
                - Description: Admin
                  Id: a058172c-4410-44e4-98ba-2b77fa5e81c3
                  PermissionGroups: ScopePermissionGroup
                  Name: Admin
                StatusCode: OK
        '400':
          description: Bad Request
      security:
      - Bearer: []
      operationId: getApiUserManagementV1RuntimeRoles
      x-operation-id-source: derived
    servers:
    - url: https://rls.congacloud.com
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
    SignerType:
      type: string
      description: Type of signer in OneSpan Sign
      x-enumNames:
      - ACCOUNT_SENDER
      - EXTERNAL_SENDER
      - EXTERNAL_SIGNER
      - GROUP_SIGNER
      - AD_HOC_GROUP_SIGNER
      enum:
      - ACCOUNT_SENDER
      - EXTERNAL_SENDER
      - EXTERNAL_SIGNER
      - GROUP_SIGNER
      - AD_HOC_GROUP_SIGNER
    External:
      type: object
      description: External integration provider settings.
      additionalProperties: false
      properties:
        data:
          type: object
          description: Provider metadata.
          additionalProperties: {}
        id:
          type: string
          description: External integration Id.
        provider:
          type: string
          description: Provider method.
        providerName:
          type: string
          description: Provider name.
    SignerInformationForEquifaxUSA:
      type: object
      description: Object to manage Equifax USA information
      additionalProperties: false
      properties:
        city:
          type: string
          description: City
        dateOfBirth:
          type:
          - string
          - 'null'
          description: Date of birth
          format: date-time
        driversLicenseNumber:
          type: string
          description: Drivers license number
        firstName:
          type: string
          description: First name
        homePhoneNumber:
          type: string
          description: Home phone number
        lastName:
          type: string
          description: Last name
        socialSecurityNumber:
          type: string
          description: Social security number
        state:
          type: string
          description: State
        streetAddress:
          type: string
          description: Street address
        timeAtAddress:
          type:
          - integer
          - 'null'
          description: Time at address
          format: int32
        zip:
          type: string
          description: Zip code
    SignerInformationForLexisNexis:
      type: object
      description: Signer identity details needed for LexisNexis verification.
      additionalProperties: false
      properties:
        firstName:
          type: string
          description: First name of the signer. (Required)
        lastName:
          type: string
          description: Last name of the signer. (Required)
        city:
          type: string
          description: City of the signer. (Required)
        zip:
          type: string
          description: ZIP or postal code of the signer. (Required)
        state:
          type: string
          description: State or province of the signer. (Optional)
        houseName:
          type: string
          description: House name of the signer’s residence. (Optional)
        flatOrApartmentNumber:
          type: string
          description: Flat or apartment number. (Optional)
        houseNumber:
          type: string
          description: House number of the signer’s residence. (Optional)
        socialSecurityNumber:
          type: string
          description: Social Security Number of the signer. (Optional)
        dateOfBirth:
          type:
          - string
          - 'null'
          description: Date of birth of the signer. (Optional)
          format: date-time
    Quota:
      type: object
      additionalProperties: false
      properties:
        cycle:
          type: string
        limit:
          type: integer
          format: int32
        scope:
          type: string
        target:
          $ref: '#/components/schemas/Target'
    RequirementStatus:
      type: string
      description: ''
      x-enumNames:
      - INCOMPLETE
      - REJECTED
      - COMPLETE
      enum:
      - INCOMPLETE
      - REJECTED
      - COMPLETE
    RoleReordering:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
          description: Role Id.
        index:
          type: integer
          description: New index of the role.
          format: int32
    Transaction:
      type: object
      additionalProperties: false
      properties:
        created:
          type:
          - string
          - 'null'
          format: date-time
        creditCard:
          $ref: '#/components/schemas/CreditCard'
        price:
          $ref: '#/components/schemas/Price'
    SignerInformationForEquifaxCanada:
      type: object
      description: Object to manage Equifax Canada information
      additionalProperties: false
      properties:
        city:
          type: string
          description: City
        dateOfBirth:
          type:
          - string
          - 'null'
          description: Date of birth
          format: date-time
        driversLicenseNumber:
          type: string
          description: Drivers license number
        firstName:
          type: string
          description: First name
        homePhoneNumber:
          type: string
          description: Home phone number
        lastName:
          type: string
          description: Last name
        socialInsuranceNumber:
          type: string
          description: Social insurance number
        province:
          type: string
          description: Province
        streetAddress:
          type: string
          description: Street address
        timeAtAddress:
          type:
          - integer
          - 'null'
          description: Time at address
          format: int32
        postalCode:
          type: string
          description: Postal code
    UserCustomField:
      type: object
      description: Object to manage a user custom field
      additionalProperties: false
      properties:
        data:
          type: object
          description: Custom data
          additionalProperties: {}
        id:
          type: string
          description: Id
        name:
          type: string
          description: Name
        translations:
          type: array
          description: List of translations
          items:
            $ref: '#/components/schemas/Translation'
        value:
          type: string
          description: Value
    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
    Address:
      type: object
      additionalProperties: false
      properties:
        address1:
          type: string
          description: Address1
        address2:
          type: string
          description: Address2
        city:
          type: string
          description: City
        country:
          type: string
          description: Country
        state:
          type: string
          description: State
        zipcode:
          type: string
          description: Zipcode
    KnowledgeBasedAuthentication:
      type: object
      description: Object to manage KBA
      additionalProperties: false
      properties:
        knowledgeBasedAuthenticationStatus:
          description: The status of the KBA
          oneOf:
          - $ref: '#/components/schemas/KnowledgeBasedAuthenticationStatus'
        signerInformationForEquifaxCanada:
          description: SignerInformationForEquifaxCanada
          oneOf:
          - $ref: '#/components/schemas/SignerInformationForEquifaxCanada'
        signerInformationForEquifaxUSA:
          description: SignerInformationForEquifaxUSA
          oneOf:
          - $ref: '#/components/schemas/SignerInformationForEquifaxUSA'
        equifaxCanada:
          type: boolean
          description: Indicates whether Equifax Canada is used for KBA.
        equifaxUSA:
          type: boolean
          description: Indicates whether Equifax USA is used for KBA.
        signerInformationForLexisNexis:
          description: Signer information required for LexisNexis identity verification.
          oneOf:
          - $ref: '#/components/schemas/SignerInformationForLexisNexis'
        lexisNexis:
          type:
          - boolean
          - 'null'
          description: Indicates whether LexisNexis is used for KBA.
    NotificationMethod:
      type: string
      description: Enumerates all available notification methods.
      x-enumNames:
      - EMAIL
      - SMS
      enum:
      - EMAIL
      - SMS
    AttachmentRequirement:
      type: object
      description: Attachment requirements and settings.
      additionalProperties: false
      properties:
        comment:
          type: string
          description: Attachment comment.
        data:
          type: object
          description: Attachment metadata.
          additionalProperties: {}
        description:
          type: string
          description: Attachment description.
        files:
          type: array
          description: Attachment files.
          items:
            $ref: '#/components/schemas/AttachmentFile'
        id:
          type: string
          description: The attachment Id.
        name:
          type: string
          description: The attachment name.
        required:
          type: boolean
          description: Is attachment required.
        status:
          description: Attachment status.
          oneOf:
          - $ref: '#/components/schemas/RequirementStatus'
    ResultOfRole:
      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/Role'
    AttachmentFile:
      type: object
      description: Attachment file information.
      additionalProperties: false
      properties:
        id:
          type: integer
          description: Attachment file Id.
          format: int32
        insertDate:
          type: integer
          description: Attachment creation date in epoch format.
          format: int64
        name:
          type: string
          description: Attachment file name.
        preview:
          type: boolean
          description: Can see attachment previews.
    Plan:
      type: object
      additionalProperties: false
      properties:
        contract:
          type: string
        cycle:
          $ref: '#/components/schemas/Cycle'
        data:
          type: object
          additionalProperties: {}
        description:
          type: string
        features:
          type: object
          additionalProperties: {}
        freeC

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