Process Street Form Field Values API

openapi: 3.2.0
info:
  title: Process Street Public Form Field Values API
  version: '1.1'
  description: The Process Street API is organized around REST.
servers:
- url: https://public-api.process.st/api/v1.1
tags:
- name: Form Field Values
  description: 'A form field value is the data entered into a form field within a workflow

    run. Use these endpoints to read and update form field values for a specific

    workflow run.'
  externalDocs:
    url: https://www.process.st/help/docs/form-fields/
    description: Process Street help article
paths:
  /workflow-runs/{workflowRunId}/tasks/{taskId}/form-fields:
    get:
      tags:
      - Form Field Values
      summary: List all form field values in a task
      description: 'Gets a page of form field values for a task of a workflow run.

        Form field values are paged, meaning the links section in the

        response must be used to get the next/previous batch of form field values.'
      operationId: listFormFieldValuesByTask
      parameters:
      - name: workflowRunId
        in: path
        description: The ID of the Workflow Run
        required: true
        schema:
          type: string
      - name: taskId
        in: path
        description: The ID of the Task
        required: true
        schema:
          type: string
      - name: _
        in: query
        description: 'Opaque pagination cursor. Take this value from the previous response''s `links[]` entry whose `name`

          is `"next"` (typically just follow that link''s `href` instead of reading this value).

          Omit on the first page. If the previous response had no `next` link, there are no more pages.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFormFieldValuesResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /workflow-runs/{workflowRunId}/form-fields:
    get:
      tags:
      - Form Field Values
      summary: List all form field values
      description: 'Gets a page of form field values for a workflow run.

        Form field values are paged, meaning the links section in the

        response must be used to get the next/previous batch of form field values.'
      operationId: listFormFieldValues
      parameters:
      - name: workflowRunId
        in: path
        description: The ID of the Workflow Run
        required: true
        schema:
          type: string
      - name: _
        in: query
        description: 'Opaque pagination cursor. Take this value from the previous response''s `links[]` entry whose `name`

          is `"next"` (typically just follow that link''s `href` instead of reading this value).

          Omit on the first page. If the previous response had no `next` link, there are no more pages.'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFormFieldValuesResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    post:
      tags:
      - Form Field Values
      summary: Batch update form field values
      description: 'Updates multiple form field values (i.e the values for the form fields present in a workflow run).

        A value may consist of a simple string, may accept multiple values as an array, or it may accept multiple

        properties.


        See the examples for a complete reference on setting form field values.


        Note: File Upload form fields cannot be updated using this endpoint. Use the upload endpoint instead.'
      operationId: batchUpdateFormFieldValues
      parameters:
      - name: workflowRunId
        in: path
        description: The ID of the Workflow Run
        required: true
        schema:
          type: string
      requestBody:
        description: 'List of form fields to set a new value for within a workflow run.

          Form field IDs included in the request will have their values created or updated.

          Form field IDs not included in the request will be left unchanged.'
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMultipleFormFieldValuesRequest'
            examples:
              updatingSimpleFields:
                summary: 'Updating a simple field: Short Text, Long Text, Email, Website, Members (User) and Dropdown fields'
                description: "Requires specifying only a 'value' key with a String associated.\n                This structure must be used for the following fields: Short Text, Long Text, Email, Website, Members (User) and Dropdown."
                value:
                  fields:
                  - id: lNOlDxX_bxK1A9JudBJFdQ
                    value: It's over Anakin, I have the high ground
              updatingMultiValueFields:
                summary: 'Updating a field that accepts multiple values: Members, Multi Select (Subtasks) and Multi Choice fields'
                description: "Requires specifying only a 'values' key with a list of Strings associated.\n                  This structure must be used for the following fields: Multi Select and Multi Choice."
                value:
                  fields:
                  - id: iGue0sTNaJ46FuE1aXNCOw
                    values:
                    - It's over Anakin
                    - I have the high ground
              dataSetConnectedDropdown:
                summary: Updating a Data Set Linked Dropdown field
                description: Requires specifying a 'value' or a 'dataSetRowId' key with a Muid associated.
                value:
                  fields:
                  - id: kvgfJO0K9G9TKPr9l1tLZw
                    value: saBkTR8rkXUjkgV5GX1M7A
              updatingDateFields:
                summary: Updating the Date field
                description: "Requires specifying only a 'value' key, but may optionally add a 'timeHidden' key.\n                  This structure must be used for the Date field."
                value:
                  fields:
                  - id: m7PvAKYLSRmyCXcBwuNIlw
                    value: '2026-07-20T14:53:23.057Z'
                    timeHidden: true
              updatingTableFields:
                summary: Updating the Table field
                description: Requires specifying only a 'value' key with a CSV associated.
                value:
                  fields:
                  - id: tpeuaFbAGzGrQrgEmu5FYQ
                    value: 'Alice,Bob

                      Jon,Natalie'
              updatingMultipleFields:
                summary: Updating multiple fields at the same time
                description: Updating multiple fields at the same time
                value:
                  fields:
                  - id: gUYeGTkY2dZbRgk1N_RPpA
                    value: '2026-07-20T14:53:23.055Z'
                    timeHidden: true
                  - id: tyOVIl1EYShtAh9ylPtK7Q
                    values:
                    - It's over Anakin
                    - I have the high ground
                  - id: tkWa_nFK1j4LgIa0w8pAYw
                    value: https://www.process.st
                  - id: jpaaqhkoAyeeOFUSFVJDtA
                    value: 'Alice,Bob

                      Jon,Natalie'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMultipleFormFieldValuesResponse'
        '400':
          description: 'Invalid value for: body'
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /workflow-runs/{workflowRunId}/form-fields/{formFieldId}/upload:
    post:
      tags:
      - Form Field Values
      summary: Upload a form field value
      description: 'Uploads one or more files to a File or MultiFile form field in a workflow run.


        Note:


        This endpoint supports both single-file and multi-file form fields.


        File fields can accept exactly one file and it will replace the current file.


        MultiFile fields can accept multiple files per request, up to 10 files total, subject to the field''s configuration.

        These files will be appended to the field.


        The maximum file size supported by this endpoint is 20 MB per file for multipart uploads and 10 MB per file for Base64 uploads.


        Alternatively, send JSON `{ "fileUploadId": "..." }` to attach a file you uploaded with the `createFileUpload` endpoint. The `fileUploadId` is single-use.'
      operationId: uploadFormFieldValue
      parameters:
      - name: workflowRunId
        in: path
        description: The ID of the Workflow Run
        required: true
        schema:
          type: string
      - name: formFieldId
        in: path
        description: Form Field ID
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadFormFieldValueRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/UploadFormFieldValueRequest'
        required: true
      responses:
        '204':
          description: ''
        '400':
          description: Invalid value
          content:
            text/plain:
              schema:
                type: string
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
    delete:
      tags:
      - Form Field Values
      summary: Delete all files from a form field
      description: Deletes all files from a File or MultiFile form field in a workflow run.
      operationId: deleteFormFieldAllFiles
      parameters:
      - name: workflowRunId
        in: path
        description: The ID of the Workflow Run
        required: true
        schema:
          type: string
      - name: formFieldId
        in: path
        description: Form Field ID
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /workflow-runs/{workflowRunId}/form-fields/{formFieldId}/upload/{fileId}:
    delete:
      tags:
      - Form Field Values
      summary: Delete a specific file from a form field
      description: 'Deletes a specific file from a File or MultiFile form field in a workflow run.

        For File fields, the `fileId` parameter is ignored since there is only one file.

        For MultiFile fields, the specified file is removed. If it was the last file, the field value is deleted entirely.'
      operationId: deleteFormFieldFileById
      parameters:
      - name: workflowRunId
        in: path
        description: The ID of the Workflow Run
        required: true
        schema:
          type: string
      - name: formFieldId
        in: path
        description: Form Field ID
        required: true
        schema:
          type: string
      - name: fileId
        in: path
        description: File ID
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
components:
  schemas:
    ListFormFieldValuesResponse:
      title: ListFormFieldValuesResponse
      type: object
      properties:
        fields:
          description: Form field definitions or column definitions, depending on context.
          type: array
          items:
            title: SimplifiedFormFieldValue
            type: object
            required:
            - id
            - workflowRunId
            - taskId
            - key
            - data
            - fieldType
            properties:
              id:
                title: EntityID
                description: The resource's ID.
                type: string
              updatedDate:
                description: When the resource was last modified. ISO-8601 UTC.
                type: string
                format: date-time
              updatedBy:
                title: PublicApiUser
                description: User who last modified the resource.
                examples:
                - id: iAaSNCU5lWLYGAi663hO8Q
                  email: jane.doe@example.com
                  username: Jane Doe
                type: object
                required:
                - id
                - email
                - username
                properties:
                  id:
                    title: EntityID
                    description: The resource's ID.
                    type: string
                  email:
                    description: The user's email address (also their login identifier).
                    type: string
                  username:
                    description: The user's display name (e.g. `Jane Doe`).
                    type: string
              workflowRunId:
                title: EntityID
                description: The ID of the Workflow Run.
                type: string
              taskId:
                title: EntityID
                description: The ID of the Task.
                type: string
              key:
                description: Unique key based on the label. This is used when referencing the form field as a [variable](https://www.process.st/help/docs/variables/)
                type: string
              label:
                description: User defined label
                type: string
              data:
                description: The form field's value, encoded as JSON. Shape depends on `fieldType` — e.g. a string for `Text`, a number for `Number`, an array of selected option keys for `MultiChoice`.
              fieldType:
                description: "Form-field subtype discriminator (only relevant when widget `type` is `FormField`).\n\n- `Text` — short text input (≤255 characters).\n- `Textarea` — long-form text.\n- `Email` — email address.\n- `Url` — website / URL.\n- `Number` — numeric input with optional unit and constraints.\n- `Date` — date or date+time picker.\n- `Select` — dropdown; user picks one option.\n- `MultiChoice` — checkboxes; user picks one or more options.\n- `MultiSelect` — Subtasks: a checklist of sub-items inside the task.\n- `Members` — assignee picker (selects organization users).\n- `File` — single file upload.\n- `MultiFile` — multi-file upload (in-app \"File Upload\").\n- `Document` — document approval field; links the task to a document review.\n- `Table` — rows × columns of cells; users fill cell values.\n- `SendRichEmail` — pre-written email embedded in the task; sent manually by the user or\n  automatically when the task is completed.\n- `Hidden` — only visible when editing the workflow; populated by integrations or default values.\n- `Snippet` — only visible when editing; passes static text or merge tags into automations.\n"
                type: string
                enum:
                - Date
                - Document
                - Email
                - File
                - Hidden
                - Members
                - MultiChoice
                - MultiFile
                - MultiSelect
                - Number
                - Select
                - SendRichEmail
                - Snippet
                - Table
                - Text
                - Textarea
                - Url
              dataSetLinked:
                description: When `true`, this field is bound to a data set row; its value is synchronised from the linked record.
                type: boolean
              links:
                description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 relation), an `href` URL, and a `type` (`Api` or `App`).
                type: array
                items:
                  title: Link
                  description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
                  type: object
                  required:
                  - name
                  - href
                  - type
                  properties:
                    name:
                      description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                      type: string
                    href:
                      title: Uri
                      description: URL of the linked resource.
                      examples:
                      - https://api.process.st/api/v1.1/resource/XXX
                      type: string
                    rel:
                      description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                      type: string
                      enum:
                      - Approval Task
                      - Approvals
                      - Assignees
                      - Comment
                      - Data Set Records
                      - Data Sets
                      - Form Field Values
                      - Subject Task
                      - Task
                      - Tasks
                      - Users
                      - Webhook
                      - Workflow
                      - Workflow Run
                    type:
                      description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                      type: string
                      enum:
                      - Api
                      - App
        links:
          description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 relation), an `href` URL, and a `type` (`Api` or `App`).
          type: array
          items:
            title: Link
            description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
            type: object
            required:
            - name
            - href
            - type
            properties:
              name:
                description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                type: string
              href:
                title: Uri
                description: URL of the linked resource.
                examples:
                - https://api.process.st/api/v1.1/resource/XXX
                type: string
              rel:
                description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                type: string
                enum:
                - Approval Task
                - Approvals
                - Assignees
                - Comment
                - Data Set Records
                - Data Sets
                - Form Field Values
                - Subject Task
                - Task
                - Tasks
                - Users
                - Webhook
                - Workflow
                - Workflow Run
              type:
                description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                type: string
                enum:
                - Api
                - App
    UploadFormFieldValueRequest:
      title: UploadFormFieldValueRequest
      type: object
      properties:
        file:
          description: Uploaded file reference. Use the upload endpoint to attach content.
          type: array
          items:
            type: string
            format: binary
        fileBase64:
          type: array
          items:
            title: FileBase64
            type: object
            required:
            - content
            - filename
            properties:
              content:
                description: Rich text content. May contain merge tags.
                type: string
              filename:
                type: string
        fileUploadId:
          type: string
    ErrorInfo:
      title: ErrorInfo
      type: object
      required:
      - error
      properties:
        error:
          description: 'Human-readable error message. Suitable for logs or for surfacing to end users; do not parse it

            programmatically — use `errorCode` for that.'
          type: string
        details:
          description: 'Optional structured context. Shape depends on the error: for `Validation` errors the keys are field

            paths; for `PaymentRequired` the keys describe the limit that was hit.'
          type: object
          additionalProperties:
            type: string
        errorCode:
          title: ErrorCode
          description: 'Machine-parsable classification of the error. Always set on responses generated by the global

            exception handler. Branch your own error handling on this (not the message text).'
          type: string
          enum:
          - BadRequest
          - Unauthorized
          - PaymentRequired
          - Forbidden
          - NotFound
          - MethodNotAllowed
          - Conflict
          - PayloadTooLarge
          - Validation
          - RateLimited
          - InternalError
        requestId:
          description: Per-request correlation ID. Include this when contacting support so we can find the request in our logs.
          type: string
    UpdateMultipleFormFieldValuesRequest:
      title: UpdateMultipleFormFieldValuesRequest
      type: object
      properties:
        fields:
          description: Form field definitions or column definitions, depending on context.
          type: array
          items:
            type: object
            required:
            - id
            properties:
              id:
                title: EntityID
                description: The resource's ID.
                type: string
              value:
                description: The form field value (e.g. text, date as ISO string, URL or user email for Users field)
                type: string
              values:
                description: List of form field values
                type: array
                items:
                  type: string
              timeHidden:
                description: Whether to hide the time portion and display the date only for Date form fields.
                type: boolean
              dataSetRowId:
                title: EntityID
                type: string
    UpdateMultipleFormFieldValuesResponse:
      title: UpdateMultipleFormFieldValuesResponse
      type: object
      properties:
        fields:
          description: Form field definitions or column definitions, depending on context.
          type: array
          items:
            title: SimplifiedFormFieldValue
            type: object
            required:
            - id
            - workflowRunId
            - taskId
            - key
            - data
            - fieldType
            properties:
              id:
                title: EntityID
                description: The resource's ID.
                type: string
              updatedDate:
                description: When the resource was last modified. ISO-8601 UTC.
                type: string
                format: date-time
              updatedBy:
                title: PublicApiUser
                description: User who last modified the resource.
                examples:
                - id: iAaSNCU5lWLYGAi663hO8Q
                  email: jane.doe@example.com
                  username: Jane Doe
                type: object
                required:
                - id
                - email
                - username
                properties:
                  id:
                    title: EntityID
                    description: The resource's ID.
                    type: string
                  email:
                    description: The user's email address (also their login identifier).
                    type: string
                  username:
                    description: The user's display name (e.g. `Jane Doe`).
                    type: string
              workflowRunId:
                title: EntityID
                description: The ID of the Workflow Run.
                type: string
              taskId:
                title: EntityID
                description: The ID of the Task.
                type: string
              key:
                description: Unique key based on the label. This is used when referencing the form field as a [variable](https://www.process.st/help/docs/variables/)
                type: string
              label:
                description: User defined label
                type: string
              data:
                description: The form field's value, encoded as JSON. Shape depends on `fieldType` — e.g. a string for `Text`, a number for `Number`, an array of selected option keys for `MultiChoice`.
              fieldType:
                description: "Form-field subtype discriminator (only relevant when widget `type` is `FormField`).\n\n- `Text` — short text input (≤255 characters).\n- `Textarea` — long-form text.\n- `Email` — email address.\n- `Url` — website / URL.\n- `Number` — numeric input with optional unit and constraints.\n- `Date` — date or date+time picker.\n- `Select` — dropdown; user picks one option.\n- `MultiChoice` — checkboxes; user picks one or more options.\n- `MultiSelect` — Subtasks: a checklist of sub-items inside the task.\n- `Members` — assignee picker (selects organization users).\n- `File` — single file upload.\n- `MultiFile` — multi-file upload (in-app \"File Upload\").\n- `Document` — document approval field; links the task to a document review.\n- `Table` — rows × columns of cells; users fill cell values.\n- `SendRichEmail` — pre-written email embedded in the task; sent manually by the user or\n  automatically when the task is completed.\n- `Hidden` — only visible when editing the workflow; populated by integrations or default values.\n- `Snippet` — only visible when editing; passes static text or merge tags into automations.\n"
                type: string
                enum:
                - Date
                - Document
                - Email
                - File
                - Hidden
                - Members
                - MultiChoice
                - MultiFile
                - MultiSelect
                - Number
                - Select
                - SendRichEmail
                - Snippet
                - Table
                - Text
                - Textarea
                - Url
              dataSetLinked:
                description: When `true`, this field is bound to a data set row; its value is synchronised from the linked record.
                type: boolean
              links:
                description: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 relation), an `href` URL, and a `type` (`Api` or `App`).
                type: array
                items:
                  title: Link
                  description: A HATEOAS link to a related resource. Use these to navigate between resources without constructing URLs by hand.
                  type: object
                  required:
                  - name
                  - href
                  - type
                  properties:
                    name:
                      description: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
                      type: string
                    href:
                      title: Uri
                      description: URL of the linked resource.
                      examples:
                      - https://api.process.st/api/v1.1/resource/XXX
                      type: string
                    rel:
                      description: Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
                      type: string
                      enum:
                      - Approval Task
                      - Approvals
                      - Assignees
                      - Comment
                      - Data Set Records
                      - Data Sets
                      - Form Field Values
                      - Subject Task
                      - Task
                      - Tasks
                      - Users
                      - Webhook
                      - Workflow
                      - Workflow Run
                    type:
                      description: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
                      type: string
                      enum:
                      - Api
                      - App
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    httpAuth:
      type: http
      description: Bearer token (beta)
      scheme: bearer
x-tagGroups:
- name: Workflows
  tags:
  - Workflows
  - Workflow Revisions
  - Form Fields
  - Workflow Logic Rules
  - Workflow Tasks
  - Workflow Task Assignment Rules
  - Workflow Widgets
  - Workflow Due Date Rules
  - Workflow Task Due Date Rules
  - Workflow Incoming Webhooks
  - Scheduled Workflows
- name: Workflow Runs
  tags:
  - Workflow Runs
  - Tasks
  - Form Field Values
  - Comments
  - Attachments
- name: Pages
  tags:
  - Pages
  - Page Revisions
  - Page Widgets
- name: Data Sets
  tags:
  - Data Sets
  - Data Set Incoming Webhooks
- name: Other
  tags:
  - Folders
  - One-Off Tasks
  - Users
  - Webhooks
  - File Uploads
  - Utilities
  - My Work