Process Street Form Fields API

openapi: 3.2.0
info:
  title: Process Street Public Form Fields 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 Fields
  description: 'A form field is a data-collection element defined on a workflow template.

    Use these endpoints to inspect the form fields and their available options

    on a workflow.'
  externalDocs:
    url: https://www.process.st/help/docs/form-fields/
    description: Process Street help article
paths:
  /workflows/{workflowId}/form-fields:
    get:
      tags:
      - Form Fields
      summary: List all form fields in a workflow
      description: 'Gets a page of form fields for a workflow.

        Form fields are paged, meaning the links section in the

        response must be used to get the next/previous batch of form fields.'
      operationId: listFormFields
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        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/ListFormFieldsResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
  /workflows/{workflowId}/form-fields/{formFieldId}/options:
    get:
      tags:
      - Form Fields
      summary: List all options for a form field
      description: 'Gets a page of form field options.


        Options are paged, meaning the links section in the response must be used to get the next/previous

        batch of form field options.

        If the field is linked to a Data Set Saved View, then the Row IDs are

        also listed in the response.'
      operationId: listFormFieldOptions
      parameters:
      - name: workflowId
        in: path
        description: The ID of the Workflow
        required: true
        schema:
          type: string
      - name: formFieldId
        in: path
        description: Form Field ID
        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/ListFormFieldOptionsResponse'
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
      security:
      - apiKeyAuth: []
      - httpAuth: []
components:
  schemas:
    ListFormFieldOptionsResponse:
      title: ListFormFieldOptionsResponse
      type: object
      properties:
        options:
          type: array
          items:
            title: FormFieldOption
            type: object
            required:
            - value
            - label
            properties:
              value:
                description: The option's stored value.
                type: string
              label:
                description: Display label shown to the end user.
                type: string
              dataSetRowId:
                title: EntityID
                type: string
        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
    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
    ListFormFieldsResponse:
      title: ListFormFieldsResponse
      type: object
      properties:
        fields:
          description: Form field definitions or column definitions, depending on context.
          type: array
          items:
            title: SimplifiedFormField
            type: object
            required:
            - id
            - audit
            - taskId
            - fieldType
            - key
            properties:
              id:
                title: EntityID
                description: The resource's ID.
                type: string
              audit:
                title: PublicApiAudit
                description: Creation and last-modification metadata.
                type: object
                required:
                - createdDate
                - createdBy
                - updatedDate
                - updatedBy
                properties:
                  createdDate:
                    description: When the resource was first created. ISO-8601 UTC.
                    type: string
                    format: date-time
                  createdBy:
                    title: PublicApiUser
                    description: User who created 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
                  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
              taskId:
                title: EntityID
                description: The ID of the Task.
                type: string
              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
              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
              dataSetLinked:
                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