OpenGov

OpenGov Record API

A Record represents a single permit or license application, code enforcement case, or business process in OpenGov Permitting & Licensing. Records are created in the Employee Portal and/or Citizen Portal and serve as the central container for all related information. This includes form data, workflows, inspections, fees, approvals, public contacts (such as applicants and guests), and associated locations.

Documentation GitHub OpenAPI

Documentation

https://developer.opengov.com/docs/plc/overview

https://developer.opengov.com/catalog/plc-api

https://developer.opengov.com/catalog/bnp-api

https://developer.opengov.com/catalog/pro-api

https://developer.opengov.com/catalog/pro-purchase-order-api

https://developer.opengov.com/catalog/pro-receipt-api

https://developer.opengov.com/docs/vm/overview

https://developer.opengov.com/catalog/vm-api

https://developer.opengov.com/docs/eam/overview

https://developer.opengov.com/catalog/eam-api

https://developer.opengov.com/catalog/opendata-public-api

Specifications

https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/openapi/opengov-record-api-openapi.yml

Other Resources

https://developer.opengov.com/docs/plc/changelog

https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/asyncapi/opengov-permitting-licensing-webhooks.yml

https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/conventions/opengov-conventions.yml

https://developer.opengov.com/docs/vm/changelog

https://developer.opengov.com/docs/eam/changes-log

OpenAPI Specification

openapi: 3.2.0
info:
  version: v2
  title: Permitting & Licensing Record 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
  description: A Record represents a single permit or license application, code enforcement case, or business process in OpenGov Permitting & Licensing. Records are created in the Employee Portal and/or Citizen Portal and serve as the central container for all related information. This includes form data, workflows, inspections, fees, approvals, public contacts (such as applicants and guests), and associated locations.
paths:
  /v2/{community}/records:
    parameters:
    - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
    get:
      summary: List records
      description: 'Retrieve records in the community that match the specified filters.


        ### Permissions Required

        `Record Read`'
      operationId: listRecords
      x-og-claims-required:
      - PLC_RECORD_READ
      tags:
      - Record
      parameters:
      - name: filter[number]
        in: query
        description: Filter by record number
        required: false
        schema:
          type: string
      - name: filter[histID]
        in: query
        description: Filter by historical ID
        required: false
        schema:
          type: string
      - name: filter[histNumber]
        in: query
        description: Filter by historical permit number
        required: false
        schema:
          type: string
      - name: filter[typeID]
        in: query
        description: Filter by record type ID
        required: false
        schema:
          type: string
      - name: filter[projectID]
        in: query
        description: Filter by project ID
        required: false
        schema:
          type: string
      - name: filter[applicantUserID]
        in: query
        description: Filter records by the user ID of their applicant
        required: false
        schema:
          type: string
      - name: filter[locationID]
        in: query
        description: Filter records by the ID of their associated location
        required: false
        schema:
          type: string
      - name: filter[status]
        in: query
        description: Filter by status
        required: false
        schema:
          type: string
          description: Status of the record
          enum:
          - STOPPED
          - DRAFT
          - ACTIVE
          - COMPLETE
      - name: filter[createdAt]
        in: query
        description: Filter by creation date
        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[updatedAt]
        in: query
        description: Filter by last updated date
        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[submittedAt]
        in: query
        description: Filter by submission date
        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[expiresAt]
        in: query
        description: Filter by expiration date
        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[isEnabled]
        in: query
        description: Filter by enabled status
        required: false
        schema:
          type: boolean
      - name: filter[renewalSubmitted]
        in: query
        description: Filter by renewal submission status
        required: false
        schema:
          type: boolean
      - name: filter[submittedOnline]
        in: query
        description: Filter by online submission status
        required: false
        schema:
          type: boolean
      - name: filter[renewalNumber]
        in: query
        description: Filter by renewal number
        required: false
        schema:
          type: string
      - name: filter[renewalOfRecordID]
        in: query
        description: Filter by renewal of record ID
        required: false
        schema:
          type: string
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/get/parameters/0'
      - $ref: '#/paths/~1v2~1{community}~1approval-steps/get/parameters/1'
      responses:
        '200':
          description: List of Records
          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'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      x-tags:
                      - Record
                      required:
                      - id
                      - type
                      - attributes
                      - relationships
                      title: Record
                      properties:
                        id:
                          type: string
                          description: Unique internal ID of a record
                          example: record-123456789
                        type:
                          type: string
                          enum:
                          - record
                          example: record
                        attributes:
                          type: object
                          required:
                          - number
                          - histID
                          - histNumber
                          - description
                          - status
                          - submittedAt
                          - expiresAt
                          - isEnabled
                          properties:
                            number:
                              type: string
                              nullable: true
                              description: External ID of a record
                              example: BP-2024-001234
                            histID:
                              type: string
                              nullable: true
                              description: Unique internal ID of the corresponding historical record
                              example: hist-567890123
                            histNumber:
                              type: string
                              nullable: true
                              description: External ID of the corresponding historical record
                              example: BP-2023-005678
                            typeDescription:
                              type: string
                              description: Description of the record's type.
                              example: Building Permit
                            status:
                              $ref: '#/paths/~1v2~1{community}~1records/get/parameters/7/schema'
                            isEnabled:
                              type: boolean
                              description: Whether the record is enabled
                              example: true
                            submittedAt:
                              type: string
                              nullable: true
                              description: Date and time (UTC) when the record is submitted
                              format: date-time
                              readOnly: true
                            expiresAt:
                              type: string
                              nullable: true
                              format: date-time
                              description: Date and time (UTC) when the record expires, or null if it does not expire
                            renewalOfRecordID:
                              type: string
                              nullable: true
                              description: Record ID of the record which this record renews
                              example: record-prev-456789
                            renewalNumber:
                              type: number
                              nullable: true
                              description: Order in the renewal series
                              example: 2
                            submittedOnline:
                              type: boolean
                              description: Submitted online
                              example: true
                            renewalSubmitted:
                              type: boolean
                              description: A renewal of this record was submitted
                              example: false
                            createdAt:
                              $ref: '#/paths/~1v2~1{community}~1record-types/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/createdAt'
                            updatedAt:
                              $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/updatedAt'
                            createdBy:
                              $ref: '#/paths/~1v2~1{community}~1record-types/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/createdBy'
                            updatedBy:
                              $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/updatedBy'
                        relationships:
                          type: object
                          required:
                          - applicant
                          - guests
                          - primaryLocation
                          - formData
                          - recordType
                          properties:
                            applicant:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/recordTypes/properties'
                              description: The applicant for the record.
                            guests:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/recordTypes/properties'
                              description: Guests of the record
                            primaryLocation:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/recordTypes/properties'
                              description: The primary location for the record.
                            additionalLocations:
                              type: object
                              properties:
                                data:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                        description: ID of the related resource
                                      type:
                                        type: string
                                        description: Type of the related resource
                                    required:
                                    - id
                                    - type
                                  minItems: 0
                                links:
                                  $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/step/properties/links'
                              description: Additional locations of the record
                            formData:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/recordTypes/properties'
                              description: Form data of the record
                            workflowSteps:
                              type: object
                              properties:
                                $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/additionalLocations/properties'
                              description: Steps of the record's workflow
                            recordType:
                              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: Record's type
                            project:
                              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: Project containing the record
                  included:
                    type: array
                    description: Related resources
                    items:
                      type: object
                      required:
                      - type
                      - id
                      - attributes
                      properties:
                        type:
                          type: string
                        id:
                          type: string
                        attributes:
                          type: object
                          additionalProperties: true
                    minItems: 0
                    maxItems: 5
                  links:
                    $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/links'
                  meta:
                    $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/200/content/application~1vnd.api+json/schema/properties/meta'
                required:
                - data
                - links
                - meta
        '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'
    post:
      summary: Create a record
      description: 'Create a record. Records are created as drafts, and can be submitted by making a subsequent `PATCH` request. (See `PATCH /records/:id`)

        ### Permissions Required

        `Record Write`'
      operationId: createRecord
      x-og-claims-required:
      - PLC_RECORD_WRITE
      tags:
      - Record
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/parameters/0'
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  title: The record object
                  properties:
                    type:
                      type: string
                      enum:
                      - record
                      example: record
                    attributes:
                      type: object
                      properties:
                        histID:
                          type: string
                          description: Unique internal ID of the corresponding historical record
                          example: hist-post-313233
                        histNumber:
                          type: string
                          description: External ID of the corresponding historical record
                          example: BP-2023-009876
                        typeID:
                          type: string
                          description: Unique ID of the record's type.
                          example: rt-building-permit
                        projectID:
                          type: string
                          description: Unique internal ID of the project this record belongs to.
                          example: proj-post-343536
                        expiresAt:
                          type: string
                          description: Date and time (UTC) when the record expires
                          format: date-time
                      required:
                      - typeID
                  required:
                  - type
                  - attributes
              required:
              - data
        required: true
      responses:
        '201':
          description: Created
          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'
            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
                    required:
                    - id
                    - type
                    - attributes
                    - relationships
                    title: Record
                    properties:
                      id:
                        type: string
                        description: Unique internal ID of a record
                        example: record-123456789
                      type:
                        type: string
                        enum:
                        - record
                        example: record
                      attributes:
                        type: object
                        required:
                        - number
                        - histID
                        - histNumber
                        - description
                        - status
                        - submittedAt
                        - expiresAt
                        - isEnabled
                        properties:
                          number:
                            type: string
                            nullable: true
                            description: External ID of a record
                            example: BP-2024-001234
                          histID:
                            type: string
                            nullable: true
                            description: Unique internal ID of the corresponding historical record
                            example: hist-567890123
                          histNumber:
                            type: string
                            nullable: true
                            description: External ID of the corresponding historical record
                            example: BP-2023-005678
                          typeDescription:
                            type: string
                            description: Description of the record's type.
                            example: Building Permit
                          status:
                            $ref: '#/paths/~1v2~1{community}~1records/get/parameters/7/schema'
                          isEnabled:
                            type: boolean
                            description: Whether the record is enabled
                            example: true
                          submittedAt:
                            type: string
                            nullable: true
                            description: Date and time (UTC) when the record is submitted
                            format: date-time
                            readOnly: true
                          expiresAt:
                            type: string
                            nullable: true
                            format: date-time
                            description: Date and time (UTC) when the record expires, or null if it does not expire
                          renewalOfRecordID:
                            type: string
                            nullable: true
                            description: Record ID of the record which this record renews
                            example: record-prev-456789
                          renewalNumber:
                            type: number
                            nullable: true
                            description: Order in the renewal series
                            example: 2
                          submittedOnline:
                            type: boolean
                            description: Submitted online
                            example: true
                          renewalSubmitted:
                            type: boolean
                            description: A renewal of this record was submitted
                            example: false
                          createdAt:
                            $ref: '#/paths/~1v2~1{community}~1record-types/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/createdAt'
                          updatedAt:
                            $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/updatedAt'
                          createdBy:
                            $ref: '#/paths/~1v2~1{community}~1record-types/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/createdBy'
                          updatedBy:
                            $ref: '#/paths/~1v2~1{community}~1departments/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/attributes/properties/updatedBy'
                      relationships:
                        type: object
                        required:
                        - applicant
                        - guests
                        - primaryLocation
                        - formData
                        - recordType
                        properties:
                          applicant:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/applicant'
                          guests:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/guests'
                          primaryLocation:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/primaryLocation'
                          additionalLocations:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/additionalLocations'
                          formData:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/formData'
                          workflowSteps:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/workflowSteps'
                          recordType:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/recordType'
                          project:
                            $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items/properties/relationships/properties/project'
                  included:
                    $ref: '#/paths/~1v2~1{community}~1departments~1{departmentID}/get/responses/200/content/application~1vnd.api+json/schema/properties/included'
                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}:
    parameters:
    - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
    - name: recordID
      in: path
      description: ID of the record
      required: true
      schema:
        type: string
    get:
      summary: Retrieve a record
      description: 'Retrieve a record by ID.

        ### Permissions Required

        `Record Read`'
      operationId: getRecord
      x-og-claims-required:
      - PLC_RECORD_READ
      tags:
      - Record
      responses:
        '200':
          description: Basic information about a record by ID
          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'
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/paths/~1v2~1{community}~1records/get/responses/200/content/application~1vnd.api+json/schema/properties/data/items'
                  included:
                    $ref: '#/paths/~1v2~1{community}~1departments~1{departmentID}/get/responses/200/content/application~1vnd.api+json/schema/properties/included'
                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 a record
      description: 'Update a record. To submit a draft record, update the status to `ACTIVE`.

        ### Permissions Required

        `Record Write`'
      operationId: updateRecord
      x-og-claims-required:
      - PLC_RECORD_WRITE
      tags:
      - Record
      parameters:
      - $ref: '#/paths/~1v2~1{community}~1approval-steps~1{approvalStepID}/patch/parameters/0'
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  title: The record object
                  required:
                  - type
                  - id
         

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/openapi/opengov-record-api-openapi.yml