OpenGov
OpenGov Approval Steps API

Approval Steps are one step type that can be found in a record's workflow.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.2.0
info:
  version: v2
  title: Permitting & Licensing Approval 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: Approval Steps
  description: Approval Steps are one step type that can be found in a record's workflow.
paths:
  /v2/{community}/approval-steps:
    parameters:
    - name: community
      in: path
      description: Subdomain of the community
      required: true
      schema:
        type: string
    get:
      summary: List approval steps
      description: 'Retrieve approval steps that match the specified filters.

        ### Permissions Required

        `Workflow Read`'
      operationId: listApprovalTasks
      x-og-claims-required:
      - PLC_RECORD_STEP_READ
      tags:
      - Approval Steps
      parameters:
      - name: page[number]
        in: query
        description: Which page to return (1-based)
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        example: 1
      - name: page[size]
        in: query
        description: Number of records to return per page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        example: 20
      - name: filter[recordID]
        in: query
        description: Filter by a recordID
        required: false
        schema:
          type: string
      - name: filter[label]
        in: query
        description: Filter by record step label
        required: false
        schema:
          type: string
      - name: filter[status]
        in: query
        description: Filter by record step status
        required: false
        schema:
          type: string
          enum:
          - REJECTED
          - INACTIVE
          - ACTIVE
          - COMPLETE
          - SKIPPED
          - ON_HOLD
          description: Status of the workflow step
      - name: filter[completedAt]
        in: query
        description: Filter by date at which the record step was completed
        required: false
        style: deepObject
        explode: true
        schema:
          oneOf:
          - type: string
          - type: object
            properties:
              lt:
                type: string
                description: Less than the specified date
              lte:
                type: string
                description: Less than or equal to the specified date
              gt:
                type: string
                description: Greater than the specified date
              gte:
                type: string
                description: Greater than or equal to the specified date
      - name: filter[activatedAt]
        in: query
        description: Filter by date at which the record step was activated
        required: false
        style: deepObject
        explode: true
        schema:
          oneOf:
          - type: string
          - type: object
            properties:
              lt:
                type: string
                description: Less than the specified date
              lte:
                type: string
                description: Less than or equal to the specified date
              gt:
                type: string
                description: Greater than the specified date
              gte:
                type: string
                description: Greater than or equal to the specified date
      - name: filter[assigneeID]
        in: query
        description: Filter by the user ID of the record step assignee
        required: false
        schema:
          type: string
      - name: filter[dueBy]
        in: query
        description: Filter by date at which the record step is due
        required: false
        style: deepObject
        explode: true
        schema:
          oneOf:
          - type: string
          - type: object
            properties:
              lt:
                type: string
                description: Less than the specified date
              lte:
                type: string
                description: Less than or equal to the specified date
              gt:
                type: string
                description: Greater than the specified date
              gte:
                type: string
                description: Greater than or equal to the specified date
      responses:
        '200':
          description: Approval step
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      x-tags:
                      - Approvals
                      title: Approval Step
                      required:
                      - type
                      - id
                      - attributes
                      properties:
                        type:
                          type: string
                          enum:
                          - approvalStep
                          example: approvalStep
                        id:
                          type: string
                          example: approval-step-100001
                        attributes:
                          type: object
                          properties:
                            label:
                              type: string
                              nullable: true
                              description: Short text that describes the workflow step
                              example: Plan Review and Approval
                            stepType:
                              type: string
                              enum:
                              - APPROVAL
                              - PAYMENT
                              - INSPECTION
                              - DOCUMENT
                              - API_INTEGRATION
                              - ASSET_MANAGEMENT
                              - RELATED_RECORD
                              - SHADOW
                              - REVIEW
                              description: A value that indicates the kind of process that this step represents
                              example: APPROVAL
                            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
                            dueBy:
                              type: string
                              format: date-time
                              nullable: true
                              description: Due date
                        relationships:
                          type: object
                          properties:
                            step:
                              type: object
                              properties:
                                data:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      description: ID of the related resource
                                    type:
                                      type: string
                                      description: Type of the related resource
                                  required:
                                  - id
                                  - type
                                  nullable: true
                                links:
                                  type: object
                                  description: Links to related resources
                                  properties:
                                    self:
                                      type: string
                                      format: uri-reference
                                      description: Link to the current resource
                                    related:
                                      type: string
                                      format: uri-reference
                                      description: Link to the related resource
                                  additionalProperties:
                                    type: string
                                    format: uri-reference
                                    description: URL of the related resource
                              description: Relationship to the step entity
                            assignee:
                              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: User assigned to the step
                  links:
                    type: object
                    description: Links to related resources in a collection
                    properties:
                      self:
                        type: string
                        format: uri-reference
                        description: Link to the current resource
                        examples:
                        - https://api.example.com/v2/records?page[number]=2&page[size]=20
                      first:
                        type: string
                        format: uri-reference
                        description: Link to the first page in the collection
                        examples:
                        - https://api.example.com/v2/records?page[number]=1&page[size]=20
                      prev:
                        type: string
                        format: uri-reference
                        description: Link to the previous page in the collection, if applicable
                        examples:
                        - https://api.example.com/v2/records?page[number]=1&page[size]=20
                      next:
                        type: string
                        format: uri-reference
                        description: Link to the next page in the collection, if applicable
                        examples:
                        - https://api.example.com/v2/records?page[number]=3&page[size]=20
                      last:
                        type: string
                        format: uri-reference
                        description: Link to the last page in the collection
                        examples:
                        - https://api.example.com/v2/records?page[number]=10&page[size]=20
                    additionalProperties:
                      type: string
                      format: uri-reference
                      description: URL of the related resource
                  meta:
                    type: object
                    required:
                    - page
                    - size
                    - totalPages
                    - totalRecords
                    properties:
                      page:
                        type: integer
                        description: The current page number
                        example: 2
                      size:
                        type: integer
                        description: Number of records per page
                        example: 20
                      totalPages:
                        type: integer
                        description: Total number of pages available
                        example: 10
                      totalRecords:
                        type: integer
                        description: Total count of records across all pages
                        example: 200
                required:
                - data
                - links
                - meta
        '400':
          description: '**Bad Request**: The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

            '
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    maxItems: 1
                    items:
                      type: object
                      required:
                      - id
                      - status
                      - title
                      - detail
                      properties:
                        id:
                          type: string
                          description: Unique identifier for this particular occurrence of the problem
                          example: error-767778
                        status:
                          type: string
                          description: The HTTP status code applicable to this problem
                          example: '400'
                        title:
                          type: string
                          description: A short summary of the problem
                          example: Validation Error
                        detail:
                          type: string
                          description: Short explanation for the specific occurrence of the problem
                          example: The provided record type ID is invalid or does not exist
        '401':
          description: '**Unauthorized**: The request has not been applied because it lacks valid authentication credentials for the target resource.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
              examples:
                unauthorized:
                  summary: Missing or invalid authentication
                  value:
                    errors:
                    - id: error-401-001
                      code: UNAUTHORIZED
                      detail: Authentication credentials are missing or invalid
                      status: '401'
                      title: Unauthorized
        '403':
          description: '**Forbidden**: The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
              examples:
                forbidden:
                  summary: Insufficient permissions
                  value:
                    errors:
                    - id: error-403-001
                      code: FORBIDDEN
                      detail: You do not have sufficient permissions to access this resource
                      status: '403'
                      title: Forbidden
        '404':
          description: '**Resource not found**: The server has not found anything matching the Request-URI. No indication is given of whether the condition is temporary or permanent.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
              examples:
                not_found:
                  summary: Resource not found
                  value:
                    errors:
                    - id: error-404-001
                      code: NOT_FOUND
                      detail: The requested resource could not be found
                      status: '404'
                      title: Not Found
        '406':
          description: '**Not Acceptable**: The server cannot produce a response matching the list of acceptable values defined in the request''s proactive content negotiation headers.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
              examples:
                not_acceptable:
                  summary: Content type not acceptable
                  value:
                    errors:
                    - id: error-406-001
                      code: NOT_ACCEPTABLE
                      detail: The requested content type is not supported. Please use application/vnd.api+json
                      source:
                        header: Accept
                      status: '406'
                      title: Not Acceptable
        '500':
          description: '**Internal Server Error**: The server encountered an unexpected condition which prevented it from fulfilling the request.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
  /v2/{community}/approval-steps/{approvalStepID}:
    parameters:
    - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
    - name: approvalStepID
      in: path
      description: ID of an approval step
      required: true
      schema:
        type: string
    get:
      summary: Get approval step
      description: 'Retrieve an approval step by ID.

        ### Permissions Required

        `Workflow Read`'
      operationId: getApprovalTask
      x-og-claims-required:
      - PLC_RECORD_STEP_READ
      tags:
      - Approval Steps
      responses:
        '200':
          description: Approval step
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    x-tags:
                    - Approvals
                    title: Approval Step
                    required:
                    - type
                    - id
                    - attributes
                    properties:
                      type:
                        type: string
                        enum:
                        - approvalStep
                        example: approvalStep
                      id:
                        type: string
                        example: approval-step-100001
                      attributes:
                        type: object
                        properties:
                          label:
                            type: string
                            nullable: true
                            description: Short text that describes the workflow step
                            example: Plan Review and Approval
                          stepType:
                            type: string
                            enum:
                            - APPROVAL
                            - PAYMENT
                            - INSPECTION
                            - DOCUMENT
                            - API_INTEGRATION
                            - ASSET_MANAGEMENT
                            - RELATED_RECORD
                            - SHADOW
                            - REVIEW
                            description: A value that indicates the kind of process that this step represents
                            example: APPROVAL
                          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
                          dueBy:
                            type: string
                            format: date-time
                            nullable: true
                            description: Due date
                      relationships:
                        type: object
                        properties:
                          step:
                            $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/step'
                          assignee:
                            $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/assignee'
                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'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
    patch:
      summary: Update approval step
      description: 'Update an approval step.

        ### Permissions Required

        `Workflow Write`'
      operationId: updateApprovalTask
      x-og-claims-required:
      - PLC_RECORD_STEP_UPDATE
      tags:
      - Approval Steps
      parameters:
      - name: Content-Type
        in: header
        required: true
        schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
          - application/json
        description: 'The Content-Type header must be set to `application/vnd.api+json` for all PUT, PATCH, and POST requests.

          '
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  required:
                  - type
                  - id
                  - attributes
                  properties:
                    type:
                      type: string
                      enum:
                      - approvalStep
                      example: approvalStep
                    id:
                      type: string
                      example: approval-step-100003
                    attributes:
                      type: object
                      properties:
                        assigneeID:
                          type: string
                          example: user-reviewer-100004
                        dueBy:
                          type: string
                          format: date-time
                          description: Due date
      responses:
        '200':
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items'
                required:
                - data
          description: Approval updated
        '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':
          description: '**Conflict**: The request could not be completed due to a conflict with the current state of the resource.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
        '415':
          description: '**Unsupported Media Type**

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/400/content/application~1vnd.api+json/schema'
              examples:
                unsupported_media_type:
                  summary: Unsupported Content-Type header
                  value:
                    errors:
                    - id: error-415-001
                      code: UNSUPPORTED_MEDIA_TYPE
                      detail: The request Content-Type is not supported. Expected application/vnd.api+json
                      source:
                        header: Content-Type
                      status: '415'
                      title: Unsupported Media Type
        '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
OpenGov Approval Steps API

Documentation

Specifications

Other Resources

OpenAPI Specification
