Moveworks smartForms API

openapi: 3.1.0
info:
  title: (Beta) Conversations authentication smartForms API
  version: 1.0.0
servers:
- url: https://api.moveworks.ai/rest/v1beta1
  description: US production server
- url: https://api.jp.moveworks.com/rest/v1beta1
  description: Japan production server
- url: https://api.uk.moveworks.com/rest/v1beta1
  description: UK production server
- url: https://api.prod4.us.moveworks.com/rest/v1beta1
  description: US Prod 4 production server
- url: https://api.prod3.us.moveworks.com/rest/v1beta1
  description: US Prod 3 production server
tags:
- name: smartForms
paths:
  /forms:
    get:
      operationId: list-forms
      summary: List Forms
      description: Forms should be returned from this API in a deterministic order. Deterministic order is desired if we decide to use pagination. Anticipated load – Moveworks will call this endpoint to iterate over all forms provided by this endpoint once every 24 hours. This API is primarily used for ingestion.
      tags:
      - smartForms
      parameters:
      - name: offset
        in: query
        description: Given a deterministically ordered list of articles, skips this many forms before returning form records
        required: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: 'Number of forms to return in a single query. Recommended max: 100 records / request.'
        required: true
        schema:
          type: integer
          format: int64
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of forms
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Smart Forms_listForms_Response_200'
  /forms/{formId}:
    get:
      operationId: get-form-by-id
      summary: Get Form By ID
      description: Form with the requested ID should be returned from this API. Anticipated load – Moveworks may call this endpoint a few times every 24 hours. This API is primarily for sanity checks and debugging. Since ingestion happens once every 24 hours, we might want to verify if form submission failures are due to deviations between the local and remote versions.
      tags:
      - smartForms
      parameters:
      - name: formId
        in: path
        description: ID of form to return
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single form
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
  /forms/{formId}/submit:
    post:
      operationId: submit-form
      summary: Submit a Form
      description: 'This API is primarily used for transactional activity. Performance will be essential. The following example assumes submission of the example form defined here. Anticipated load – Moveworks will call this endpoint every time a user submits a form through our native skill. '
      tags:
      - smartForms
      parameters:
      - name: formId
        in: path
        description: ID of form to submit
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful form submission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitFormResponse'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                submitted_by:
                  type: string
                  description: System ID (usually the email address) of the user who submitted this form.
                fields:
                  $ref: '#/components/schemas/FormsFormIdSubmitPostRequestBodyContentApplicationJsonSchemaFields'
                  description: This is a dictionary where they keys are the "field names" coming from the schema, and the value types are string, list of strings, and boolean. See the example.
                form_metadata:
                  $ref: '#/components/schemas/FormsFormIdSubmitPostRequestBodyContentApplicationJsonSchemaFormMetadata'
              required:
              - submitted_by
components:
  schemas:
    Rule:
      type: object
      properties:
        name:
          type: string
          description: Unique identifier for the rule within the form.
        logical:
          $ref: '#/components/schemas/RuleLogical'
          description: The logical operator to use to combine the conditions
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/Condition'
          description: Specifies the conditions that when met, will kick off actions. If the conditions go from met to unmet, the actions will be reversed as well.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: Specifies the actions to be taken if the conditions are met.
      required:
      - name
      - conditions
      - actions
      title: Rule
    Option:
      type: object
      properties:
        label:
          type: string
          description: The display value for this option. This will be displayed to the end user.
        value:
          type: string
          description: The response value for this option. This will be used as the field value during form submission.
      required:
      - label
      - value
      title: Option
    Field:
      type: object
      properties:
        name:
          type: string
          description: Unique name for the field in the form. Will be used as the key (in a key-value pair) during form submission.
        label:
          type: string
          description: Label for the field. This will be displayed to the end user.
        placeholder:
          type: string
          description: Placeholder text to be shown in the field. This will be displayed to the end user.
        help:
          type: string
          description: Tooltip (or additional help text) for the field. This will be displayed to the end user.
        type:
          $ref: '#/components/schemas/FieldType'
          description: The type of the field.
        default_to_current_user:
          type: boolean
          default: false
          description: For SINGLE_USER_OPTION_PICKER and MULTI_USER_OPTION_PICKER field types only. The value defaults (auto-fills) to the end user filling the form.
        options:
          type: array
          items:
            $ref: '#/components/schemas/Option'
          description: For SINGLE_OPTION_PICKER and MULTI_OPTION_PICKER field types only.
        required:
          type: boolean
          default: false
          description: Conveys whether the field is mandatory during form submission.
        visible:
          type: boolean
          default: true
          description: Conveys whether the field is initially hidden when the form is displayed to the end user.
      required:
      - name
      - label
      - type
      title: Field
    ConditionValue:
      oneOf:
      - type: boolean
      - type: string
      - type: array
        items:
          type: string
      description: 'field_name''s value will be compared against this value using the operator specified above. Note: When the operator is EMPTY, NOT_EMPTY, this attribute need not be specified.'
      title: ConditionValue
    Form:
      type: object
      properties:
        id:
          type: string
          description: Stable unique identifier for the form.
        image_url:
          type: string
          description: Publically accessible image URL for the form
        domain:
          $ref: '#/components/schemas/FormDomain'
          description: Specifies the domain the form belongs to.
        title:
          type: string
          description: Title of the form. This will be displayed to the end user.
        description:
          type: string
          description: A long description of the form’s purpose. This is used in our form search machine learning, and is also displayed to the end user.
        short_description:
          type: string
          description: A short description of the form’s purpose. This is used in our form search machine learning, and is also displayed to the end user.
        url:
          type: string
          description: Self-service portal URL where the user can fill out the form if in-bot form filling is not supported.
        last_updated_at:
          type: string
          description: Last updated date as a ISO-8601 UTC timestamp (e.g., 2021-10-20T17:28:52Z)
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
          description: A list of fields that make up this form.
        dynamic_field_rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
          description: A list of rules that specify dynamic form field behavior based on user response to other fields.
      required:
      - id
      - domain
      - title
      - url
      - last_updated_at
      title: Form
    SubmitFormResponse:
      type: object
      properties:
        ticket_id:
          type: string
          description: The display ticket ID of the ticket that was created (if any). null value is allowed. If a valid ticket ID is returned, Moveworks will be able to fetch/poll this ticket to provide updates to the user and to accelerate resolution of their request.
      title: SubmitFormResponse
    FormsFormIdSubmitPostRequestBodyContentApplicationJsonSchemaFormMetadata:
      type: object
      properties:
        name:
          type: string
          description: The name of the form being submitted
        last_updated_at:
          type: string
          description: Last updated date as a ISO-8601 UTC timestamp (e.g., 2021-10-20T17:28:52Z). Indicates the freshness of the form.
      required:
      - name
      - last_updated_at
      title: FormsFormIdSubmitPostRequestBodyContentApplicationJsonSchemaFormMetadata
    FormDomain:
      type: string
      enum:
      - IT
      - HR
      description: Specifies the domain the form belongs to.
      title: FormDomain
    FieldType:
      type: string
      enum:
      - LABEL
      - SINGLE_OPTION_PICKER
      - MULTI_OPTION_PICKER
      - SINGLE_USER_OPTION_PICKER
      - MULTI_USER_OPTION_PICKER
      - SINGLE_LINE_TEXT
      - MULTI_LINE_TEXT
      - CHECKBOX
      - DATE_PICKER
      - DATETIME_PICKER
      description: The type of the field.
      title: FieldType
    Smart Forms_listForms_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Form'
      title: Smart Forms_listForms_Response_200
    ConditionOperator:
      type: string
      enum:
      - EMPTY
      - NOT_EMPTY
      - IN
      - NOT_IN
      - EQUALS
      - NOT_EQUALS
      description: The operator to use to inspect the field_name's value.
      title: ConditionOperator
    Action:
      type: object
      properties:
        field_name:
          type: string
          description: Name of the target field to take action on.
        visible:
          type: boolean
          description: Marks the target field as visible or hidden when the conditions are met.
        required:
          type: boolean
          description: Marks the target field as required or optional when the conditions are met.
      required:
      - field_name
      - visible
      - required
      title: Action
    RuleLogical:
      type: string
      enum:
      - AND
      - OR
      description: The logical operator to use to combine the conditions
      title: RuleLogical
    Condition:
      type: object
      properties:
        field_name:
          type: string
          description: Name of the field whose value needs to be inspected.
        operator:
          $ref: '#/components/schemas/ConditionOperator'
          description: The operator to use to inspect the field_name's value.
        value:
          $ref: '#/components/schemas/ConditionValue'
          description: 'field_name''s value will be compared against this value using the operator specified above. Note: When the operator is EMPTY, NOT_EMPTY, this attribute need not be specified.'
      required:
      - field_name
      - operator
      title: Condition
    FormsFormIdSubmitPostRequestBodyContentApplicationJsonSchemaFields:
      type: object
      properties: {}
      description: This is a dictionary where they keys are the "field names" coming from the schema, and the value types are string, list of strings, and boolean. See the example.
      title: FormsFormIdSubmitPostRequestBodyContentApplicationJsonSchemaFields
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: JWT bearer token authentication. Obtain an access token from the Moveworks auth endpoint and include it in the Authorization header as 'Bearer <token>'.