OpenGov Record Guests API

openapi: 3.2.0
info:
  version: v2
  title: Permitting & Licensing Record Guests 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 Guests
  description: 'Record Guests are additional users who need visibility into the permit/license process. This could include

    contractors, architects, property owners, or other stakeholders who need to track the application''s progress,

    receive updates, or help manage the application. For example, a homeowner (Applicant) might add their

    contractor (Guest) to a building permit to help upload revised plans or respond to inspector comments.


    A record can have up to 10 Guests. The Applicant or any employee user can add Guests to a Record.


    '
paths:
  /v2/{community}/records/{recordID}/guests:
    parameters:
    - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
    - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
    get:
      summary: List record guests
      description: 'List all guests associated with a record.


        ### Permissions Required

        `Record Read`'
      operationId: listRecordGuests
      x-og-claims-required:
      - PLC_RECORD_READ
      tags:
      - Record Guests
      responses:
        '200':
          description: Guests related to a record
          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:
                      - Users
                      - Record Guests
                      required:
                      - id
                      - type
                      - attributes
                      title: User
                      properties:
                        type:
                          type: string
                          enum:
                          - user
                        id:
                          type: string
                          description: The user ID
                        attributes:
                          type: object
                          properties:
                            firstName:
                              type: string
                              description: First name of the user
                              example: John
                            lastName:
                              type: string
                              description: Last name of the user
                              example: Doe
                            email:
                              type: string
                              description: Email of the user
                              example: john.doe@example.com
                            phoneNo:
                              type: string
                              description: Phone number of the user
                              example: 123-456-7890
                            address:
                              type: string
                              description: Address 1
                              example: 123 Main St
                            address2:
                              type: string
                              description: Address 2
                              example: Apt 1
                            city:
                              type: string
                              description: City
                              example: Anytown
                            state:
                              type: string
                              description: State
                              example: CA
                            zip:
                              type: string
                              description: ZIP Code
                              example: '12345'
                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'
    post:
      summary: Add a guest
      description: 'Add a new guest to the record. Records can have multiple guests but only one applicant.


        A record can have up to 10 guests. If the limit is exceeded, the API will return a `422 Unprocessable Entity`.


        ### Permissions Required

        `Record Write`'
      operationId: addRecordGuest
      x-og-claims-required:
      - PLC_RECORD_WRITE
      tags:
      - Record Guests
      parameters:
      - $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
                  required:
                  - type
                  - id
                  properties:
                    type:
                      type: string
                      enum:
                      - user
                    id:
                      type: string
                      description: The user ID to add as a guest
                      example: U-123456789
              required:
              - data
      responses:
        '201':
          description: Guest successfully added
          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:
                    $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1guests/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'
        '422':
          description: Validation error
          content:
            application/vnd.api+json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    maxItems: 1
                    items:
                      type: object
                      required:
                      - status
                      - code
                      - title
                      - detail
                      - source
                      properties:
                        status:
                          type: string
                          enum:
                          - '422'
                        code:
                          type: string
                          enum:
                          - GUEST_LIMIT_EXCEEDED
                        title:
                          type: string
                          example: Maximum guest limit exceeded
                        detail:
                          type: string
                          example: The number of guests cannot exceed 10. Please remove an existing guest before adding a new one.'
                        source:
                          type: object
                          properties:
                            pointer:
                              type: string
                              example: /data/0/attributes/value
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
  /v2/{community}/records/{recordID}/guests/{userID}:
    parameters:
    - $ref: '#/paths/~1v2~1{community}~1approval-steps/parameters/0'
    - $ref: '#/paths/~1v2~1{community}~1records~1{recordID}~1additional-locations/get/parameters/1'
    - name: userID
      in: path
      description: ID of the user
      required: true
      schema:
        type: string
    get:
      summary: Retrieve a guest
      description: 'Retrieve a guest user on a record.

        ### Permissions Required

        `Record Read`'
      operationId: getRecordGuest
      x-og-claims-required:
      - PLC_RECORD_READ
      tags:
      - Record Guests
      responses:
        '200':
          description: Guest related to record
          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~1{recordID}~1guests/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'
        '500':
          $ref: '#/paths/~1v2~1{community}~1approval-steps/get/responses/500'
    delete:
      summary: Remove a guest
      description: 'Remove a guest from a record. Note that the applicant cannot be removed through this endpoint.

        ### Permissions Required

        `Record Write`'
      operationId: removeRecordGuest
      x-og-claims-required:
      - PLC_RECORD_WRITE
      tags:
      - Record Guests
      responses:
        '204':
          description: Guest successfully removed
          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'
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