OpenGov Record Workflow Steps API

openapi: 3.2.0
info:
  version: v2
  title: Permitting & Licensing Record Workflow Steps API
  contact:
    name: OpenGov Permitting & Licensing API
    url: https://opengov.com
    email: developers@opengov.com
  description: "The OpenGov Permitting & Licensing API provides programmatic access to Permitting & Licensing data and workflows. With this API, you can integrate with other systems, build custom applications, or automate tasks. \n\nThe API is designed around REST principles, supports JSON:API standards, and exposes resources such as records, inspections, fees, approvals, and user accounts. This documentation covers available endpoints, request and response formats, and error codes, helping developers extend and integrate OpenGov Permitting & Licensing securely and efficiently.\n"
  license:
    name: OpenGov Permitting & Licensing API
    url: https://opengov.com
servers:
- url: https://api.plce.opengov.com/plce
  description: Production
  x-og-envs:
  - production
  - staging
  - development
  - local
security:
- bearerAuth: []
- basicHttpAuthentication: []
- auth0Prod: []
- auth0Dev: []
tags:
- name: Record Workflow Steps
  description: 'A Record''s Workflow is represented as a collection of **Steps**. Steps are automatically created on a Record at the time it is submitted, based on the Record Type Workflow defined for that Record''s Type.


    Steps are instantiated on Records and can be added or deleted on individual Records, so a given Record''s Steps may not always match its Workflow Template.

    '
paths:
  /v2/{community}/records/{recordID}/workflow-steps:
    get:
      summary: List record workflow steps
      description: 'List workflow steps on a record.

        ### Permissions Required

        `Workflow Read`'
      operationId: listRecordSteps
      x-og-claims-required:
      - PLC_RECORD_STEP_READ
      tags:
      - Record Workflow Steps
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
      - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
      responses:
        '200':
          description: Workflow steps of a record
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      x-tags:
                      - Record Workflow Steps
                      title: Record Workflow Step
                      required:
                      - type
                      - id
                      - attributes
                      description: 'A record step represents a step in a workflow of a record.


                        Overview:

                        - The record step object contains information about the step, including its label, type, and status

                        - It maintains relationships with other objects like comments and workflow steps

                        - Each step is associated with a specific Task type that is created upon step activation


                        Task Relationship:

                        - The Task type is determined by the step type (e.g., an APPROVAL step creates an ApprovalTask)

                        - Tasks contain their own information (label, status) and maintain a relationship back to their step

                        - Each Task type has distinct schemas, API operations, and lifecycles

                        - Tasks can be either manual (completed by users) or automated (completed by systems)


                        Completion Rules:

                        A step cannot be marked as complete until its corresponding Task is completed.

                        '
                      properties:
                        type:
                          type: string
                          enum:
                          - workflowStep
                          example: workflowStep
                        id:
                          type: string
                          example: step-789012
                        attributes:
                          type: object
                          properties:
                            label:
                              type: string
                              nullable: true
                              description: Short text that describes the workflow step
                              example: Review Application
                            stepType:
                              $ref: '#/paths/~1v2~1{community}~1record-types~1{recordTypeID}~1workflow/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/stepType'
                            ordinal:
                              type: integer
                              description: Order in which the steps are activated in the workflow
                              example: 1
                            sequence:
                              type: boolean
                              description: ''
                              example: true
                            status:
                              $ref: '#/paths/~1v2~1{community}~1approval-steps/get/parameters/4/schema'
                            activatedAt:
                              type: string
                              format: date-time
                              description: When the step was activated
                            completedAt:
                              type: string
                              nullable: true
                              format: date-time
                              description: When the step was completed
                            visible:
                              type: boolean
                              description: Indicates whether the step is visible to users
                              example: true
                        relationships:
                          type: object
                          properties:
                            record:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/step/properties'
                              description: The record associated with the record step.
                            templateStep:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/step/properties'
                              description: The related template step
                            comments:
                              $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                            approvalTask:
                              $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                            documentTask:
                              $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                            inspectionTask:
                              $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                            paymentTask:
                              $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                          required:
                          - record
                          - comments
                required:
                - data
          headers:
            X-RateLimit-Limit:
              $ref: '#/paths/~1v2~1{community}~1files/post/responses/201/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/paths/~1v2~1{community}~1files/post/responses/201/headers/X-RateLimit-Remaining'
        '400':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400'
        '401':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/401'
        '403':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/403'
        '404':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/404'
        '406':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/406'
        '409':
          $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/responses/409'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
    post:
      summary: Add a record workflow step
      operationId: addRecordWorkflowStep
      x-og-claims-required:
      - PLC_RECORD_STEP_CREATE
      tags:
      - Record Workflow Steps
      description: 'Add a workflow step to a record.

        ### Permissions Required

        `Workflow Write`'
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
      - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
      - $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/parameters/0'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  title: Record Workflow Step
                  required:
                  - type
                  - attributes
                  properties:
                    type:
                      type: string
                      enum:
                      - workflowStep
                      example: workflowStep
                    attributes:
                      type: object
                      properties:
                        label:
                          type: string
                          description: Short text that describes the workflow step
                          example: Technical Review
                        stepType:
                          type: string
                          enum:
                            $ref: '#/paths/~1v2~1{community}~1record-types~1{recordTypeID}~1workflow/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/stepType/enum'
                          description: A value that indicates the kind of process that this step represents
                          example: APPROVAL
                        templateID:
                          type: integer
                          description: Identifier for the template of this workflow step
                          example: 798081
                        ordinal:
                          type: integer
                          description: Order in which the steps are activated in the workflow
                          example: 3
                        sequence:
                          type: boolean
                          description: ''
                          example: true
                        status:
                          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/parameters/4/schema'
      responses:
        '201':
          description: Returns the record workflow step
          headers:
            Location:
              $ref: '#/paths/~1v2~1{community}~1inspection-events/post/responses/201/headers/Location'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    x-tags:
                    - Record Workflow Steps
                    title: Record Workflow Step
                    required:
                    - type
                    - id
                    - attributes
                    description: 'A record step represents a step in a workflow of a record.


                      Overview:

                      - The record step object contains information about the step, including its label, type, and status

                      - It maintains relationships with other objects like comments and workflow steps

                      - Each step is associated with a specific Task type that is created upon step activation


                      Task Relationship:

                      - The Task type is determined by the step type (e.g., an APPROVAL step creates an ApprovalTask)

                      - Tasks contain their own information (label, status) and maintain a relationship back to their step

                      - Each Task type has distinct schemas, API operations, and lifecycles

                      - Tasks can be either manual (completed by users) or automated (completed by systems)


                      Completion Rules:

                      A step cannot be marked as complete until its corresponding Task is completed.

                      '
                    properties:
                      type:
                        type: string
                        enum:
                        - workflowStep
                        example: workflowStep
                      id:
                        type: string
                        example: step-789012
                      attributes:
                        type: object
                        properties:
                          label:
                            type: string
                            nullable: true
                            description: Short text that describes the workflow step
                            example: Review Application
                          stepType:
                            $ref: '#/paths/~1v2~1{community}~1record-types~1{recordTypeID}~1workflow/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/stepType'
                          ordinal:
                            type: integer
                            description: Order in which the steps are activated in the workflow
                            example: 1
                          sequence:
                            type: boolean
                            description: ''
                            example: true
                          status:
                            $ref: '#/paths/~1v2~1{community}~1approval-steps/get/parameters/4/schema'
                          activatedAt:
                            type: string
                            format: date-time
                            description: When the step was activated
                          completedAt:
                            type: string
                            nullable: true
                            format: date-time
                            description: When the step was completed
                          visible:
                            type: boolean
                            description: Indicates whether the step is visible to users
                            example: true
                      relationships:
                        type: object
                        properties:
                          record:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1workflow-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/record'
                          templateStep:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1workflow-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/templateStep'
                          comments:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                          approvalTask:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                          documentTask:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                          inspectionTask:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                          paymentTask:
                            $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1form/get/responses/200/content/application~1vnd.api+json/schema/properties/included/items/properties/relationships/properties/entries'
                        required:
                        - record
                        - comments
                required:
                - data
        '400':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400'
        '401':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/401'
        '403':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/403'
        '404':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/404'
        '406':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/406'
        '409':
          $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/responses/409'
        '415':
          $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/responses/415'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
  /v2/{community}/records/{recordID}/workflow-steps/{stepID}:
    get:
      summary: Retrieve a step
      description: 'Retrieve a step on a record.

        ### Permissions Required

        `Workflow Read`'
      operationId: getStep
      x-og-claims-required:
      - PLC_RECORD_STEP_READ
      tags:
      - Record Workflow Steps
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
      - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
      - name: stepID
        in: path
        description: ID of a workflow step on a record
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Workflow step on a record
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1workflow-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items'
                required:
                - data
          headers:
            X-RateLimit-Limit:
              $ref: '#/paths/~1v2~1{community}~1files/post/responses/201/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/paths/~1v2~1{community}~1files/post/responses/201/headers/X-RateLimit-Remaining'
          links:
            record:
              operationId: getRecord
              parameters:
                community: $request.path.community
                recordID: $response.body.data.relationships.record.data.id
            self:
              operationId: getStep
              parameters:
                community: $request.path.community
                recordID: $request.path.recordID
                stepID: $request.path.stepID
            approvalTask:
              operationId: getApprovalTask
              parameters:
                community: $request.path.community
                taskID: $response.body.data.relationships.approvalTask.data.id
            inspectionTask:
              operationId: getInspectionTask
              parameters:
                community: $request.path.community
                taskID: $response.body.data.relationships.inspectionTask.data.id
            paymentTask:
              operationId: getPaymentTask
              parameters:
                community: $request.path.community
                taskID: $response.body.data.relationships.paymentTask.data.id
        '400':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400'
        '401':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/401'
        '403':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/403'
        '404':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/404'
        '406':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/406'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
    delete:
      summary: Delete step
      description: 'Remove a step from a record.

        ### Permissions Required

        `Workflow Write`'
      operationId: deleteStep
      x-og-claims-required:
      - PLC_RECORD_STEP_UPDATE
      tags:
      - Record Workflow Steps
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
      - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
      - name: stepID
        in: path
        description: ID of a workflow step on a record
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Workflow step deleted
          headers:
            X-RateLimit-Limit:
              $ref: '#/paths/~1v2~1{community}~1files/post/responses/201/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/paths/~1v2~1{community}~1files/post/responses/201/headers/X-RateLimit-Remaining'
        '400':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400'
        '401':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/401'
        '403':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/403'
        '404':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/404'
        '406':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/406'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
    patch:
      summary: Update a step
      operationId: updateStep
      x-og-claims-required:
      - PLC_RECORD_STEP_UPDATE
      tags:
      - Record Workflow Steps
      description: 'Update a record workflow step''s properties.

        ### Permissions Required

        `Workflow Write`'
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
      - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
      - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1workflow-steps~1{stepID}/delete/parameters/2'
      - $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/parameters/0'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  title: Record Workflow Step
                  required:
                  - type
                  - id
                  - attributes
                  properties:
                    type:
                      type: string
                      enum:
                      - workflowStep
                      example: workflowStep
                    id:
                      type: string
                      example: step-patch-828384
                    attributes:
                      type: object
                      properties:
                        label:
                          type: string
                          nullable: true
                          description: Short text that describes the workflow step
                          example: Updated Technical Review
                        status:
                          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/parameters/4/schema'
                        ordinal:
                          type: integer
                          description: Order in which the steps are activated in the workflow
                          example: 4
                        sequence:
                          type: boolean
                          description: ''
                          example: true
      responses:
        '200':
          description: Workflow step updated
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1workflow-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items'
                required:
                - data
        '400':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400'
        '401':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/401'
        '403':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/403'
        '404':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/404'
        '406':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/406'
        '409':
          $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/responses/409'
        '415':
          $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/responses/415'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
components:
  securitySchemes:
    basicHttpAuthentication:
      type: http
      scheme: basic
      description: 'Basic HTTP Authentication

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'The OpenGov Permitting & Licensing API is authenticated using the OAuth2 Client Credentials flow. Access tokens are provided as a bearer token Authorization header in all API requests.

        To obtain an access token, you must have an OpenGov-provided Client ID and Client Secret.

        Access tokens are obtained by making a POST request to `https://accounts.viewpointcloud.com/oauth/token`

        '
    auth0Prod:
      type: openIdConnect
      openIdConnectUrl: https://accounts.viewpointcloud.com/.well-known/openid-configuration
      description: 'The OpenGov Permitting & Licensing API is authenticated using the OAuth2 Client Credentials flow. Access tokens are provided as a bearer token Authorization header in all API requests.

        To obtain an access token, you must have an OpenGov-provided Client ID and Client Secret.

        '
    auth0Dev:
      type: openIdConnect
      openIdConnectUrl: https://login.vpctest.com/.well-known/openid-configuration
      description: 'The OpenGov Permitting & Licensing API is authenticated using the OAuth2 Client Credentials flow. Access tokens are provided as a bearer token Authorization header in all API requests.

        To obtain an access token, you must have an OpenGov-provided Client ID and Client Secret.

        '
x-og-spec-id: plc-api-v2
x-og-claims:
  PLC_RECORD_READ: Record Read
  PLC_RECORD_WRITE: Record Write
  PLC_RECORD_ARCHIVE: Record Archive
  PLC_RECORD_STEP_READ: Workflow Read
  PLC_RECORD_STEP_CREATE: Workflow Write
  PLC_RECORD_STEP_UPDATE: Workflow Write
  PLC_RECORD_STEP_COMMENT_READ: Comment Read
  PLC_RECORD_STEP_COMMENT_WRITE: Comment Write
  PLC_USER_READ: User Read
  PLC_USER_WRITE: User Write
  PLC_RECORD_TYPE_READ: Record Type Read
  PLC_SYSTEM_CONFIG_READ: System Config Read
  PLC_LOCATION_READ: Location Read
  PLC_LOCATION_WRITE: Location Write
  PLC_PAYMENT_READ: Payment Read
  PLC_PAYMENT_WRITE: Payment Write
  PLC_FILE_READ: File Read
  PLC_FILE_WRITE: File Write
  PLC_ACTIVITY_LOG_READ: Activity Log Read
x-tagGroups:
- name: Records
  tags:
  - Record
  - Record Applicant
  - Record Guests
  - Record Primary Location
  - Record Additional Locations
  - Record Forms
  - Record Change Requests
  - Record Attachments
  - Record Workflow Steps
  - Record Workflow Step Comments
- name: Locations
  tags:
  - Locations
  - Location Flags
- name: Users
  tags:
  - Users
  - User Flags
- name: Approvals
  tags:
  - Approval Steps
- name: Documents
  tags:
  - Document Steps
  - Issued Documents
- name: Inspections
  tags:
  - Inspection Steps
  - Inspection Types
  - Inspection Events
  - Inspection Results
  - Checklist Results
- name: Payments
  tags:
  - Payment Steps
  - Fees
  - Transactions
  - Ledger Entries
- name: Projects
  tags:
  - Projects
- name: Files
  tags:
  - Files
- name: Configuration
  tags:
  - Organization
  - Departments
  - Record Types
  - Record Type Form
  - Record Type Attachments
  - Record Type Document Templates
  - Record Type Fees
  - Record Type Workflow
  - Inspection Type Templates
  - Checklist Templates
- name: Activity Logs
  tags:
  - Activity Logs