openapi: 3.2.0
info:
  version: 1.0.0
  x-logo:
    url: https://developers.unqork.io/unqork-logo.png
    backgroundColor: '#FFFFFF'
  title: Unqork Customer Users API
  description: "\nUnqork's customer REST API, based on open standards, allows you to set and retrieve module submission data, as well as control other aspects of your Unqork environment. You can use any web development language to access the API, as communication is over secured HTTP.\n## URI Structure and Methods\nAll API communication will occur over SSL (HTTPS). All API responses are in JSON format.\nAll Unqork requests begin with the prefix:\n\n```\n  https://{yourSubdomain}.unqork.io/api/1.0\n```\n\nFor example, if your subdomain is **xyzfinancial**, you would use the prefix `https://xyzfinancial.unqork.io/api/1.0`.\n\nThe next segment of the URI path will vary based on the endpoint of the request.\n\nA given endpoint (resource) has a series of actions (methods) associated with it. The Unqork API supports these standard HTTP methods:\n\n- **GET** - retrieves data\n\n- **PUT** - updates existing data\n\n- **POST** - creates new data\n\n- **DELETE** - deletes existing data\n\nFor example, you can use the POST action on the module submission resource to create a new module submission.\n## Paging\nPaged endpoints use the [Link header](https://www.w3.org/wiki/LinkHeader). If the link header \"next\" is present, then there are more items to retrieve, and the \"next\" should be followed.\n## Cloud Storage Delivery\nUnqork exposes generated PDFs, uploaded attachments, and other file-like pieces of submission data via Cloud Storage Delivery URLs. These are signed, expiring links that allow the user to securely retrieve files stored in Unqork. Links can appear inside raw submission data, or they can be returned from PDF transform submission endpoints.\n\nThese links cannot be shared with other parties; only the user who generates the unique link (by either submitting the file or accessing the submission where the file has been saved) will be able to use that specifically generated link. This means that the user must be authenticated (either in the browser, or by passing a valid OAuth Bearer token) in order to retrieve the file.\n\nCloud Storage Delivery URLs will look like this:\n\n`https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}`\n\nThe file can be retrieved by accessing the link in the browser, or like this:\n\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}\n```\n## Nomenclature\nPreviously, \"Modules\" were called \"Forms\". This nomenclature change affects all endpoints documented here in paths, request parameters, and response bodies (e.g. `forms -> modules`, `formId -> moduleId`; however, the behaviors of the endpoints are the same. The previous endpoints will continue to be supported, but they will be deprecated in the future.\n## API Access Notes\n#### Express Module and Workflow Access <a name=\"express-module-workflow-access\"></a>\nExpress Module and Workflow Access is determined by a User's Role and the Module's permissions. An Express User's Role is specified at the environment level, but can be overwritten at the Application level using Application Roles. If Module Permissions are used, the permission settings will specify what access (Read, Write, Obfuscate, or None) a User will have to the Module. Anonymous Users may also be able to access a Module if the permission settings allow it.\n#### Submission Access <a name=\"submission-access\"></a>\nSubmission Access is determined by a User's Role, Groups, and if they are the owner of the Submission. A Submission owner is the user that created or updated the Submission. If a user is a Submission owner, Designer Administrator, or an Express Super User, the user has access to the Submission. If the User does not have access to the Module or Workflow that the Submission is associated with, then the User will not have access to the Submission. See Express Module and Workflow Access ([Express Module and Workflow Access](#express-module-workflow-access)). A User's Role Groups can also provide a User Access to a Submission. A User needs to have Intersecting Groups with the Submission Owner. Intersecting Groups means a User has a Role with a Group (Groups assigned directly to the User do not count) that is in the Submission owner's groups (the Submission owners Role Groups or the Submission owners User Groups). If a User has Intersecting Groups:\n- And the Group type is ignore role, a User that has Intersecting Groups can access the Submission.\n- And the Group type is Role descendents, a User that has Intersecting Groups and the Submission owner's Role is a descendant of the User's Role then the User can access the Submission.\n- And the Group type is own Role and descendents, a User that has Intersecting Groups and the Submission owner's Role is a descendent of the User's Role or the User's Role is the same as the Submission owner's Role then the User can access the Submission.\n"
servers:
- url: https://{host}/api/1.0
  variables:
    host:
      default: env.unqork.io
      description: Environment host
security:
- OAuth2: []
tags:
- name: Users
  description: '

    The following endpoints are available to "Administrator" users only.

    '
paths:
  /users:
    get:
      tags:
      - Users
      summary: Get Users
      operationId: getUsers
      description: "Returns Express user objects. This is a paged endpoint (see Paging).\n### Authorization Required:\n  - Designer Administrator\n"
      parameters:
      - name: limit
        in: query
        description: Maximum number of results to return (default 50, maximum 500)
        required: false
        schema:
          type: integer
          format: int32
          default: 50
          maximum: 500
      - name: sort
        in: query
        description: Field to sort by. Use [field name] for ascending and -[field name] for descending order. You can `,` seperate for multiple sort orders.
        required: false
        schema:
          type: string
      - name: filter
        in: query
        description: "Filter conditions for searching users, formatted like `?filter=name=Bill`. The filters should be `;` separated, as shown below. Supported fields are \"role\", \"name\", \"phone\", \"email\", \"userId\", \"groups\", \"applicationRoles\". All filter conditions are \"starts with\". NOTE: When filtering on `created` and `modified`, all timestamps are in UTC. You need to encode reserved url characters if they are part of the data you are filtering.  Example, * ' ( ) : @ & = + $ , / ? % # [ ] You need to double encode `;` as `%253B` if it is a part of the data you are filtering.\n\nExamples:\n  - `filter=email=john@doe.com` will fetch all users starting with email \"john@doe.com\"\n  - `filter=filter={\"name\":{\"$eq\":\"john@doe.com\"}}` will fetch all users that exactly match \"john@doe.com\"\n  - `filter=role=Admin;created>2019-06-11T21:50:57.067Z` will fetch all user with role starting with \"Admin\" and created after \"2019-06-11T21:50:57.067Z\" (UTC)\n  - `filter=modified=2019-06-11T21:50:57.067Z` will fetch users modified at exactly \"2019-06-11T21:50:57.067Z\" (UTC)\n  - `filter=created>2019-06-11T00:00:00.000Z;created<2019-06-20T00:00:00.000Z` will fetch users created between \"2019-06-11T00:00:00.000Z\" (UTC) and \"2019-06-20T00:00:00.000Z\" (UTC)\n\n\nSupported operators (as specified in this library [api-query-params](https://github.com/loris/api-query-params)):\n  - key=val  `type=public`\n  - key>val  `count>5`\n  - key>=val  `rating>=9.5`\n  - key<val  `createdAt<2016-01-01`\n  - key<=val  `score<=-5`\n  - key!=val  `status!=success`\n  - key=val1,val2  `country=GB,US`\n  - key!=val1,val2  `lang!=fr,en`\n  - key  `phone`\n  - !key  `!email`\n  - key=/value/<opts>  `email=/@gmail\\.com$/i`\n  - key!=/value/<opts> `phone!=/^06/`\n\nNote: multiple forward slashes (/) are interpreted as a regex. To use a string comparison wrap your parameter with string(). Ex. email=string(/@gmail\\.com$/i).\n"
        schema:
          type: string
      - name: showServiceUsers
        in: query
        description: "Whether to allow show all users or all non service users. Note - The value should be passed as true/false\nExamples:\n  - `showServiceUsers=true` will show all the users in the system\n  - `showServiceUsers=false` will show all the non service users\n  - If the argument is not passed, by default all non service users will be displayed.\n"
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      tags:
      - Users
      summary: Create User
      operationId: createUser
      description: "Creates a new user. If userId is not specified, it is auto-generated and returned.\n### Authorization Required:\n  - Designer Administrator\n"
      parameters:
      - name: shouldNotify
        in: query
        description: Whether to notify the user via email of their temporary password.
        schema:
          type: boolean
      - name: skipTemporaryPassword
        in: query
        description: Whether to set the user's password as permanent immediately. A password must be provided in the body if this flag is set. This flag cannot be used if "shouldNotify" is also set.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPost'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}:
    get:
      tags:
      - Users
      summary: Get User
      operationId: getUser
      description: "Returns an Express user object based on a user ID.\n### Authorization Required:\n  - Designer Administrator\n"
      parameters:
      - name: userId
        in: path
        description: ID of user to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
      - Users
      summary: Update User
      operationId: updateUser
      description: "Updates a single user. Partial updates are supported. To delete a specific custom attribute, pass null for that attribute.\n### Authorization Required:\n  - Designer Administrator\n"
      parameters:
      - name: userId
        in: path
        description: ID of user to update
        required: true
        schema:
          type: string
      - name: shouldNotify
        in: query
        description: 'Controls the distribution of the **New Account (Token Invitation)** email.


          * `true`: Sends both the "New Account" email and the "User Changed" email.

          * `false`: Suppresses the "New Account" email only. The "User Changed" email is still sent to the user.


          Note: This parameter acts specifically on the Token Invitation workflow and does not globally suppress all system notifications.'
        schema:
          type: boolean
          default: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPut'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
      - Users
      summary: Delete User
      operationId: deleteUser
      description: "Deletes a user based on the user ID supplied. Note that users are hard-deleted, and this is not reversible. If a user is a system user, it cannot be deleted.\n### Authorization Required:\n  - Designer Administrator\n"
      parameters:
      - name: userId
        in: path
        description: ID of user to delete
        required: true
        schema:
          type: string
      responses:
        '204':
          description: User deleted
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}/passwordStatus:
    get:
      tags:
      - Users
      summary: Get User Password Status
      operationId: getUserPasswordStatus
      description: "Returns the user's password status based on a user ID.\n### Authorization Required:\n  - Designer Administrator\n"
      parameters:
      - name: userId
        in: path
        description: ID of user to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: User Password Status
          content:
            application/json:
              schema:
                type: object
                required:
                - userId
                - passwordStatus
                properties:
                  userId:
                    type: string
                  passwordStatus:
                    type: string
                    description: 'Status of the user''s password:

                      * `TEMPORARY` - User must change password at first login. If temporary password has expired, a new one must be resent using PUT.

                      * `OK` - User has already changed their temporary password.

                      * `FORCED_RESET` - User has to reset their password.

                      * `N/A` - Not applicable

                      '
                    enum:
                    - OK
                    - TEMPORARY
                    - N/A
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UserPut:
      type: object
      properties:
        userId:
          type: string
          description: 'The unique identifier of the user account. The userId can only include letters, numbers, and the following characters @,+-_.


            **Immutable**: This value cannot be modified. If provided in the request body, it must match the `userId` in the path, or it will be ignored.'
        name:
          type: string
          description: The name can only include letters, numbers, and the following characters @,+-_.'
        email:
          type: string
          maxLength: 254
          format: email
          description: Quotes and special characters `"(),:;<>@[]\` are not allowed. The local portion of the email (e.g. local@domain.com) must be > 0 characters and < 64 charaters. There cannot be consecutive dots (e.g. `..`) in the email
        phone:
          type: string
          description: Must be a valid US phone number unless the country code is specified, in which case it is validated with [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js#definitions)
        role:
          type: string
          description: One of the roles configured in Unqork
          deprecated: true
        expressRoles:
          type: array
          items:
            type: string
          description: Express roles configured in Unqork
        groups:
          type: array
          items:
            type: string
          description: List of groups configured in Unqork OR comma-separated list of groups configured in Unqork (e.g. "group1,group2")
        applicationRoles:
          type: object
          description: Map of applications to roles OR comma-separated list of application-role mappings (e.g. "application1:role1,application2:role2")
        password:
          type: string
          format: password
        isServiceUser:
          type: boolean
          format: true/false
        '...customAttributes':
          type: string
          description: Custom attributes can be included as additional keys in the request body. Only string values of custom attributes are supported.
    UserResponse:
      type: object
      required:
      - userId
      - name
      - email
      - created
      - modified
      properties:
        userId:
          type: string
        name:
          type: string
        email:
          type: string
        phone:
          type: string
        role:
          type: string
          description: One of the roles configured in Unqork
          default: Authenticated
          deprecated: true
        expressRoles:
          type: array
          items:
            type: string
          description: Express roles configured in Unqork
          default:
          - Authenticated
        groups:
          type: array
          items:
            type: string
          description: List of groups configured in Unqork
          default: []
        applicationRoles:
          type: object
          description: Map of applications to roles
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        isServiceUser:
          type: boolean
          format: true/false
        lastLogin:
          type: string
          format: date-time
        '...customAttributes':
          type: string
          description: Custom attributes will be included as additional keys in the response body.
    UserPost:
      type: object
      required:
      - name
      - email
      properties:
        userId:
          type: string
          description: The userId can only include letters, numbers, and the following characters @,+-_.
        name:
          type: string
          description: The name can only include letters, numbers, and the following characters @,+-_.'
        email:
          type: string
          maxLength: 254
          format: email
          description: Quotes and special characters `"(),:;<>@[]\` are not allowed. The local portion of the email (e.g. local@domain.com) must be > 0 characters and < 64 charaters. There cannot be consecutive dots (e.g. `..`) in the email
        phone:
          type: string
          description: Must be a valid US phone number unless the country code is specified, in which case it is validated with [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js#definitions)
        role:
          type: string
          description: One of the roles configured in Unqork
          default: Authenticated
          deprecated: true
        expressRoles:
          type: array
          items:
            type: string
          description: Express roles configured in Unqork
          default:
          - Authenticated
        groups:
          type: array
          items:
            type: string
          description: List of groups configured in Unqork OR comma-separated list of groups configured in Unqork (e.g. "group1,group2")
          default: []
        applicationRoles:
          type: object
          description: Map of applications to roles OR comma-separated list of application-role mappings (e.g. "application1:role1,application2:role2")
        password:
          type: string
          format: password
        isServiceUser:
          type: boolean
          format: true/false
        '...customAttributes':
          type: string
          description: Custom attributes can be included as additional keys in the request body. Only string values of custom attributes are supported.
    Error:
      type: object
      description: Error
      required:
      - code
      - message
      properties:
        code:
          description: HTTP status code
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
  securitySchemes:
    OAuth2:
      description: "The Unqork API implements the [OAuth 2.0 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) and the [OAuth 2.0 Password Grant](https://tools.ietf.org/html/rfc6749#section-1.3.3). Access via OAuth2 Client Credentials Grant can be utilized by creating Client Credentials through the API Access Management Administration page. Access via OAuth2 Password Grant can be enabled for all users in Environment Administration. Once OAuth2 Password Grant is enabled, all Unqork users can use their Unqork username/password to retrieve an access token.\n\nIn order to utilize any of the API resources, you must first retrieve an access token by POSTing your credentials to the access token URL, e.g. using `curl`:\n```\n  $ curl -u '{clientId}:{clientSecret}' -X POST --basic https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=client_credentials\"\n```\nOr:\n```\n  $ curl -X POST https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=password&username={username}&password={password}\"\n```\nThis returns an \"access_token\", which you would then retain and use in any subsequent resource requests. **Access tokens expire after one hour, at which point you must retrieve a new one.** The access token should be included in a request header:\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/api/1.0/{endpoint}\n```\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A
        password:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A