OpenGov Steps API

openapi: 3.2.0
info:
  version: v1
  title: Permitting Licensing & Code Enforcement Steps API
  x-logo:
    url: https://viewpointcloud.blob.core.windows.net/profile-pictures/Frame_778_Sun_Nov_12_2023_17:18:36_GMT+0000_(Coordinated_Universal_Time).png
  description: "The OpenGov Permitting & Licensing API is organized around REST. The API is based on the JSON API specification and uses standard HTTP response codes, authentication, and verbs.\n\n## Authentication\nThe OpenGov Permitting & Licensing API is authenticated using the [OAuth2](https://www.rfc-editor.org/rfc/rfc6749) Client Credentials flow. Access tokens are provided as a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750) Authorization header in all API requests.\n\nTo obtain an access token, you must have an OpenGov-provided **Client ID** and **Client Secret** and make a POST request to https://accounts.viewpointcloud.com/oauth/token\n\nExample request:\n\n```bash\ncurl --request POST \\\n  --url https://accounts.viewpointcloud.com/oauth/token \\\n  --header 'content-type: application/x-www-form-urlencoded' \\\n  --data 'grant_type=client_credentials' \\\n  --data 'client_id=YOUR_CLIENT_ID' \\\n  --data 'client_secret=YOUR_CLIENT_SECRET' \\\n  --data 'audience=viewpointcloud.com/api/production'\n```\n\nThe response will include:\n- `access_token`: Access token issued by the authorization server\n- `token_type`: Type of token issued (typically `Bearer`)\n- `expires_in`: The lifetime in seconds of the access token\n<br />\n<br />\nThe API will return a 401 error if a token is invalid.\n<br />\n<br />\n"
servers:
- url: https://api.plce.opengov.com/plce
  description: Production
security:
- bearerAuth: []
tags:
- name: 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 Workflow Template defined in the Record Type settings of 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:
  /v1/{community}/records/{recordID}/workflow-steps:
    get:
      summary: List record steps
      operationId: listRecordSteps
      tags:
      - Steps
      parameters:
      - $ref: '#/components/parameters/community'
      - $ref: '#/components/parameters/recordID'
      responses:
        '200':
          description: Returns record steps
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecordStep'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource not found
        '500':
          description: Internal Server Error
  /v1/{community}/records/{recordID}/workflow-steps/{stepID}:
    get:
      summary: Retrieve a record step
      operationId: getStepDetails
      tags:
      - Steps
      parameters:
      - $ref: '#/components/parameters/community'
      - $ref: '#/components/parameters/recordID'
      - $ref: '#/components/parameters/stepID'
      responses:
        '200':
          description: Returns the record step object
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/RecordStep'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource not found
        '500':
          description: Internal Server Error
  /v1/{community}/records/{recordID}/workflow-steps/{stepID}/state:
    put:
      summary: Update a record step
      operationId: setStepState
      tags:
      - Steps
      description: Update the status of a workflow step
      parameters:
      - $ref: '#/components/parameters/community'
      - $ref: '#/components/parameters/recordID'
      - $ref: '#/components/parameters/stepID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/RecordStepState'
      responses:
        '200':
          description: Step Updated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RecordStep'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Resource not found
        '500':
          description: Internal Server Error
components:
  schemas:
    step_status:
      type: string
      enum:
      - REJECTED
      - INACTIVE
      - ACTIVE
      - COMPLETE
      - SKIPPED
      - ON_HOLD
      description: Status of the workflow step
    RecordStepState:
      type: object
      properties:
        id:
          type: string
          description: ID of the resource
        type:
          type: string
          description: Type of the resource
          enum:
          - record_step_state
        attributes:
          type: object
          properties:
            state:
              type: string
              enum:
              - REJECTED
              - INACTIVATED
              - ACTIVATED
              - COMPLETED
              - SKIPPED
              - ON_HOLD
    relationship:
      type: object
      properties:
        links:
          type: object
          properties:
            related:
              type: string
              description: Link to the related resource
    RecordStep:
      x-tags:
      - Steps
      type: object
      title: The record step object
      example:
        type: record_step
        id: '59577'
        attributes:
          id: 59577
          label: Intake Review
          type: APPROVAL
          templateID: 962
          ordinal: 0
          sequence: 'true'
          status: COMPLETED
          assigneeID: auth0|56x389536x623x407x134487
          activatedAt: '2022-07-08T16:30:12.120Z'
          dueBy: null
        relationships:
          comments:
            links:
              related: /plce/v1/community/records/31598/workflow-steps/59577/comments
      properties:
        type:
          type: string
          enum:
          - record_step
        id:
          type: integer
        attributes:
          type: object
          properties:
            id:
              type: integer
              description: Identifier for a step in record's workflow
            label:
              type: string
              description: Short text that describes the workflow step
            type:
              type: string
              enum:
              - APPROVAL
              - PAYMENT
              - INSPECTION
              - DOCUMENT
              - API_INTEGRATION
              description: A value that indicates the kind of process that this step represents
            templateID:
              type: integer
              description: Identifier for the template of this workflow stemp
            ordinal:
              type: integer
              description: Order in which the steps are activated in the workflow
            sequence:
              type: integer
              description: ''
            status:
              $ref: '#/components/schemas/step_status'
            assigneeID:
              type: integer
            activatedAt:
              type: string
              format: date-time
            dueBy:
              type: string
              format: date-time
        relationships:
          type: object
          properties:
            comments:
              $ref: '#/components/schemas/relationship'
  parameters:
    stepID:
      name: stepID
      in: path
      description: ID of workflow step on a record
      required: true
      schema:
        type: integer
    community:
      name: community
      in: path
      description: Name of the community
      required: true
      schema:
        type: string
    recordID:
      name: recordID
      in: path
      description: ID of the record
      required: true
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-tagGroups:
- name: Records
  tags:
  - Records
  - Record Contacts
  - Record Locations
  - Record Form
- name: Workflow
  tags:
  - Steps
  - Step Comments
- name: Events
  tags:
  - Event Types