OpenGov

OpenGov Contracts API

The Contracts API from OpenGov — 10 operation(s) for contracts.

GitHub OpenAPI

Documentation

📖
Documentation
https://developer.opengov.com/docs/plc/overview
📖
APIReference
https://developer.opengov.com/catalog/plc-api
📖
APIReference
https://developer.opengov.com/catalog/bnp-api
📖
APIReference
https://developer.opengov.com/catalog/pro-api
📖
APIReference
https://developer.opengov.com/catalog/pro-purchase-order-api
📖
APIReference
https://developer.opengov.com/catalog/pro-receipt-api
📖
Documentation
https://developer.opengov.com/docs/vm/overview
📖
APIReference
https://developer.opengov.com/catalog/vm-api
📖
Documentation
https://developer.opengov.com/docs/eam/overview
📖
APIReference
https://developer.opengov.com/catalog/eam-api
📖
APIReference
https://developer.opengov.com/catalog/opendata-public-api

Specifications

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

Other Resources

🔗
ChangeLog
https://developer.opengov.com/docs/plc/changelog
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/asyncapi/opengov-permitting-licensing-webhooks.yml
🔗
Idempotency
https://raw.githubusercontent.com/api-evangelist/opengov/refs/heads/main/conventions/opengov-conventions.yml
🔗
ChangeLog
https://developer.opengov.com/docs/vm/changelog
🔗
ChangeLog
https://developer.opengov.com/docs/eam/changes-log

OpenAPI Specification

opengov-contracts-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Opengov Contracts API
  version: '1.0'
  description: 'Operations tagged Contracts across 2 of this provider''s published API definitions: opengov-procurement-v1-openapi.yml, opengov-procurement-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.procurement.opengov.com
  description: Production
tags:
- name: Contracts
  x-displayName: Contracts
paths:
  /gateway/contract-orders/v1:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    post:
      tags:
      - Contracts
      summary: Import Contract Orders
      operationId: importContractOrders
      security:
      - basicAuth: []
      - apiKeyAuth: []
      - xApiKeyHeaderAuth: []
      requestBody:
        description: A JSON array of Contract Orders to be imported.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ContractOrder'
      responses:
        '200':
          description: Successfully updated one or more Contract Orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  createdCount:
                    type: integer
                    example: 2
                    description: Number of Contract Orders created.
                  updatedCount:
                    type: integer
                    example: 1
                    description: Number of Contract Orders updated.
                  erroredContractOrders:
                    type: array
                    description: List of Contract Orders that encountered errors.
                    items:
                      $ref: '#/components/schemas/ErroredContractOrder'
        '201':
          description: Successfully created one or more Contract Orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  createdCount:
                    type: integer
                    example: 2
                    description: Number of Contract Orders created.
                  updatedCount:
                    type: integer
                    example: 1
                    description: Number of Contract Orders updated.
                  erroredContractOrders:
                    type: array
                    description: List of Contract Orders that encountered errors.
                    items:
                      $ref: '#/components/schemas/ErroredContractOrder'
        '400':
          description: Bad request, invalid or empty body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No valid contract orders to import
                  erroredContractOrders:
                    type: array
                    description: List of Contract Orders that encountered errors.
                    items:
                      $ref: '#/components/schemas/ErroredContractOrder'
        '401':
          description: Unauthorized, invalid or missing token.
        '403':
          description: Forbidden, user does not have permission to import contract orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Only contract admins can import contract orders
        '404':
          description: Not Found, feature is not available in this environment.
        '500':
          description: Internal server error.
  /public/api/v1/contracts:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint fetches a list of contracts, ordered by their ID, and supports cursor-based pagination.
      operationId: ListContractsV1Controller_listContracts
      parameters:
      - name: first
        required: false
        in: query
        description: The number of contracts to return.
        schema:
          default: 5
          example: 10
          type: number
      - name: after
        required: false
        in: query
        description: A cursor for use in pagination.
        schema:
          example: Y29udHJhY3QuaWQ9MQ==
          type: string
      - name: startDateAfter
        required: false
        in: query
        description: Filters out all contracts with startDate after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: startDateBefore
        required: false
        in: query
        description: Filters out all contracts with startDate before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: createdDateAfter
        required: false
        in: query
        description: Filters out all contracts with created_at after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: createdDateBefore
        required: false
        in: query
        description: Filters out all contracts with created_at before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: endDateAfter
        required: false
        in: query
        description: Filters out all contracts with endDate after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: endDateBefore
        required: false
        in: query
        description: Filters out all contracts with endDate before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: updatedDateAfter
        required: false
        in: query
        description: Filters out all contracts updated after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: updatedDateBefore
        required: false
        in: query
        description: Filters out all contracts updated before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: sortByAsc
        required: false
        in: query
        description: Sorts, in ascending order, the final list by the valid contract field
        schema:
          example: title
          type: string
      - name: sortByDesc
        required: false
        in: query
        description: Sorts, in descending order, the final list by the valid contract field
        schema:
          example: title
          type: string
      - name: externalVendorId
        required: false
        in: query
        description: Filters contracts by External Vendor ID (case-insensitive substring match).
        schema:
          example: vendor-123
          type: string
      responses:
        '200':
          description: A paginated list of contracts was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContractsResponseDto'
        '400':
          description: The request parameters are invalid.
          content:
            application/json:
              examples:
                Invalid `first` parameter (not an integer):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be an integer'
                    error: Bad Request
                Invalid `first` parameter (negative value):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be a non-negative number'
                    error: Bad Request
                Malformed `after` cursor:
                  value:
                    statusCode: 400
                    message: Invalid `after` cursor, please only use cursors generated by this API
                    error: Bad Request
                Filtering startDate misordered:
                  value:
                    statusCode: 400
                    message: startDateBefore is earlier than startDateAfter
                    error: Bad Request
                Attempting to sort by invalid field:
                  value:
                    statusCode: 400
                    message: Attempting to sort by invalid field id
                    error: Bad Request
                Attempting to sort both ascending and descending:
                  value:
                    statusCode: 400
                    message: Provide only one of sortByAsc or sortByDesc
                    error: Bad Request
                General request validation errors:
                  value:
                    statusCode: 400
                    message: Validation error on query parameter property
                    error: Bad Request
        '401':
          content:
            application/json:
              examples:
                Missing Authorization Header:
                  value:
                    statusCode: 401
                    message: Authorization header not found
                    error: Unauthorized
                Missing Authorization Value:
                  value:
                    statusCode: 401
                    message: Authorization header value not found
                    error: Unauthorized
                Invalid Authorization Header:
                  value:
                    statusCode: 401
                    message: Invalid authorization header
                    error: Unauthorized
                Token Verification Failed:
                  value:
                    statusCode: 401
                    message: Token verification failed
                    error: Unauthorized
                API Key Authentication Failed:
                  value:
                    statusCode: 401
                    message: API key authentication failed
                    error: Unauthorized
                Incomplete User Information:
                  value:
                    statusCode: 401
                    message: 'User or entity information incomplete: userUUID=undefined, entityUUID=undefined'
                    error: Unauthorized
                Failed to Get Entitlements:
                  value:
                    statusCode: 401
                    message: Failed to get entitlements
                    error: Unauthorized
          description: ''
        '403':
          content:
            application/json:
              examples:
                Missing Required Entitlements:
                  value:
                    statusCode: 403
                    message: 'Required entitlements not found: PLATFORM_ADMIN_SETTINGS_ENTITLEMENT, PRO_ENTITLEMENT'
                    error: Forbidden
                Not a Member of Requested Entity:
                  value:
                    statusCode: 403
                    message: User is not a member of the requested entity
                    error: Forbidden
                No Associated Government Organization:
                  value:
                    statusCode: 403
                    message: No associated government organization found for user
                    error: Forbidden
          description: ''
        '404':
          content:
            application/json:
              examples:
                Requested Entity Not Found:
                  value:
                    statusCode: 404
                    message: Requested entity not found
                    error: Not Found
          description: ''
        '500':
          content:
            application/json:
              examples:
                Server Error:
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
          description: ''
      summary: List of Contracts
      tags:
      - Contracts
      security:
      - BearerToken: []
      - APIKey: []
  /public/api/v1/contracts/{id}:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint fetches a contract based on its unique ID.
      operationId: ListContractsV1Controller_getContractById
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: The contract was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractByIdResponseDetails'
        '401':
          content:
            application/json:
              examples:
                Missing Authorization Header:
                  value:
                    statusCode: 401
                    message: Authorization header not found
                    error: Unauthorized
                Missing Authorization Value:
                  value:
                    statusCode: 401
                    message: Authorization header value not found
                    error: Unauthorized
                Invalid Authorization Header:
                  value:
                    statusCode: 401
                    message: Invalid authorization header
                    error: Unauthorized
                Token Verification Failed:
                  value:
                    statusCode: 401
                    message: Token verification failed
                    error: Unauthorized
                API Key Authentication Failed:
                  value:
                    statusCode: 401
                    message: API key authentication failed
                    error: Unauthorized
                Incomplete User Information:
                  value:
                    statusCode: 401
                    message: 'User or entity information incomplete: userUUID=undefined, entityUUID=undefined'
                    error: Unauthorized
                Failed to Get Entitlements:
                  value:
                    statusCode: 401
                    message: Failed to get entitlements
                    error: Unauthorized
          description: ''
        '403':
          content:
            application/json:
              examples:
                Missing Required Entitlements:
                  value:
                    statusCode: 403
                    message: 'Required entitlements not found: PLATFORM_ADMIN_SETTINGS_ENTITLEMENT, PRO_ENTITLEMENT'
                    error: Forbidden
                Not a Member of Requested Entity:
                  value:
                    statusCode: 403
                    message: User is not a member of the requested entity
                    error: Forbidden
                No Associated Government Organization:
                  value:
                    statusCode: 403
                    message: No associated government organization found for user
                    error: Forbidden
          description: ''
        '404':
          description: The contract with the specified ID was not found.
          content:
            application/json:
              examples:
                Contract Not Found:
                  value:
                    statusCode: 404
                    message: Contract not found
                    error: Not Found
                Requested Entity Not Found:
                  value:
                    statusCode: 404
                    message: Requested entity not found
                    error: Not Found
        '500':
          content:
            application/json:
              examples:
                Server Error:
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
          description: ''
      summary: Contract by ID
      tags:
      - Contracts
      security:
      - BearerToken: []
      - APIKey: []
  /public/api/v1/contracts/{id}/attachments:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint fetches all attachments associated with a contract by contract ID.
      operationId: ListContractsV1Controller_getContractAttachments
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: The attachment metadata were successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttachmentResponseDto'
        '401':
          content:
            application/json:
              examples:
                Missing Authorization Header:
                  value:
                    statusCode: 401
                    message: Authorization header not found
                    error: Unauthorized
                Missing Authorization Value:
                  value:
                    statusCode: 401
                    message: Authorization header value not found
                    error: Unauthorized
                Invalid Authorization Header:
                  value:
                    statusCode: 401
                    message: Invalid authorization header
                    error: Unauthorized
                Token Verification Failed:
                  value:
                    statusCode: 401
                    message: Token verification failed
                    error: Unauthorized
                API Key Authentication Failed:
                  value:
                    statusCode: 401
                    message: API key authentication failed
                    error: Unauthorized
                Incomplete User Information:
                  value:
                    statusCode: 401
                    message: 'User or entity information incomplete: userUUID=undefined, entityUUID=undefined'
                    error: Unauthorized
                Failed to Get Entitlements:
                  value:
                    statusCode: 401
                    message: Failed to get entitlements
                    error: Unauthorized
          description: ''
        '403':
          content:
            application/json:
              examples:
                Missing Required Entitlements:
                  value:
                    statusCode: 403
                    message: 'Required entitlements not found: PLATFORM_ADMIN_SETTINGS_ENTITLEMENT, PRO_ENTITLEMENT'
                    error: Forbidden
                Not a Member of Requested Entity:
                  value:
                    statusCode: 403
                    message: User is not a member of the requested entity
                    error: Forbidden
                No Associated Government Organization:
                  value:
                    statusCode: 403
                    message: No associated government organization found for user
                    error: Forbidden
          description: ''
        '404':
          description: No Contract found matching Contract ID
          content:
            application/json:
              examples:
                Contract Not Found:
                  value:
                    statusCode: 404
                    message: Contract not found
                    error: Not Found
                Requested Entity Not Found:
                  value:
                    statusCode: 404
                    message: Requested entity not found
                    error: Not Found
        '500':
          content:
            application/json:
              examples:
                Server Error:
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
          description: ''
      summary: Attachments
      tags:
      - Contracts
      security:
      - BearerToken: []
      - APIKey: []
  /public/api/v1/contracts/{id}/contacts:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint returns the customizable contacts associated with a contract (Contacts subtab).
      operationId: ListContractsV1Controller_getContractContacts
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: The contacts were successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactsResponseDto'
        '401':
          content:
            application/json:
              examples:
                Missing Authorization Header:
                  value:
                    statusCode: 401
                    message: Authorization header not found
                    error: Unauthorized
                Missing Authorization Value:
                  value:
                    statusCode: 401
                    message: Authorization header value not found
                    error: Unauthorized
                Invalid Authorization Header:
                  value:
                    statusCode: 401
                    message: Invalid authorization header
                    error: Unauthorized
                Token Verification Failed:
                  value:
                    statusCode: 401
                    message: Token verification failed
                    error: Unauthorized
                API Key Authentication Failed:
                  value:
                    statusCode: 401
                    message: API key authentication failed
                    error: Unauthorized
                Incomplete User Information:
                  value:
                    statusCode: 401
                    message: 'User or entity information incomplete: userUUID=undefined, entityUUID=undefined'
                    error: Unauthorized
                Failed to Get Entitlements:
                  value:
                    statusCode: 401
                    message: Failed to get entitlements
                    error: Unauthorized
          description: ''
        '403':
          content:
            application/json:
              examples:
                Missing Required Entitlements:
                  value:
                    statusCode: 403
                    message: 'Required entitlements not found: PLATFORM_ADMIN_SETTINGS_ENTITLEMENT, PRO_ENTITLEMENT'
                    error: Forbidden
                Not a Member of Requested Entity:
                  value:
                    statusCode: 403
                    message: User is not a member of the requested entity
                    error: Forbidden
                No Associated Government Organization:
                  value:
                    statusCode: 403
                    message: No associated government organization found for user
                    error: Forbidden
          description: ''
        '404':
          description: Contract not found
          content:
            application/json:
              examples:
                Contract Not Found:
                  value:
                    statusCode: 404
                    message: Contract not found
                    error: Not Found
                Requested Entity Not Found:
                  value:
                    statusCode: 404
                    message: Requested entity not found
                    error: Not Found
        '500':
          content:
            application/json:
              examples:
                Server Error:
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
          description: ''
      summary: Contacts
      tags:
      - Contracts
      security:
      - BearerToken: []
      - APIKey: []
  /gateway/v2/entities/{entityUuid}/contract-orders:
    parameters:
    - $ref: '#/components/parameters/EntityUuidPathParam'
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    post:
      tags:
      - Contracts
      summary: Import Contract Orders
      operationId: importContractOrdersV2
      security:
      - basicAuth: []
      - apiKeyAuth: []
      - xApiKeyHeaderAuth: []
      requestBody:
        description: A JSON array of Contract Orders to be imported.
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ContractOrder'
      responses:
        '200':
          description: Successfully updated one or more Contract Orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  createdCount:
                    type: integer
                    example: 2
                    description: Number of Contract Orders created.
                  updatedCount:
                    type: integer
                    example: 1
                    description: Number of Contract Orders updated.
                  erroredContractOrders:
                    type: array
                    description: List of Contract Orders that encountered errors.
                    items:
                      $ref: '#/components/schemas/ErroredContractOrder'
        '201':
          description: Successfully created one or more Contract Orders.
          content:
            application/json:
              schema:
                type: object
                properties:
                  createdCount:
                    type: integer
                    example: 2
                    description: Number of Contract Orders created.
                  updatedCount:
                    type: integer
                    example: 1
                    description: Number of Contract Orders updated.
                  erroredContractOrders:
                    type: array
                    description: List of Contract Orders that encountered errors.
                    items:
                      $ref: '#/components/schemas/ErroredContractOrder'
        '400':
          description: Bad request, invalid or empty body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: No valid contract orders to import
                  erroredContractOrders:
                    type: array
                    description: List of Contract Orders that encountered errors.
                    items:
                      $ref: '#/components/schemas/ErroredContractOrder'
        '401':
          description: Unauthorized, invalid or missing token.
        '403':
          $ref: '#/components/responses/MissingProEntitlement'
        '404':
          description: Not Found, feature is not available in this environment.
        '500':
          description: Internal server error.
  /public/api/v2/entities/{entityUuid}/contracts:
    servers:
    - url: https://api.procurement.opengov.com
      description: Production
    get:
      description: This endpoint fetches a list of contracts, ordered by their ID, and supports cursor-based pagination.
      operationId: ListContractsV2Controller_listContracts
      parameters:
      - name: first
        required: false
        in: query
        description: The number of contracts to return.
        schema:
          default: 5
          example: 10
          type: number
      - name: after
        required: false
        in: query
        description: A cursor for use in pagination.
        schema:
          example: Y29udHJhY3QuaWQ9MQ==
          type: string
      - name: startDateAfter
        required: false
        in: query
        description: Filters out all contracts with startDate after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: startDateBefore
        required: false
        in: query
        description: Filters out all contracts with startDate before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: createdDateAfter
        required: false
        in: query
        description: Filters out all contracts with created_at after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: createdDateBefore
        required: false
        in: query
        description: Filters out all contracts with created_at before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: endDateAfter
        required: false
        in: query
        description: Filters out all contracts with endDate after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: endDateBefore
        required: false
        in: query
        description: Filters out all contracts with endDate before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: updatedDateAfter
        required: false
        in: query
        description: Filters out all contracts updated after this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: updatedDateBefore
        required: false
        in: query
        description: Filters out all contracts updated before this date (ISO8601).
        schema:
          example: '2025-01-01'
          type: string
      - name: sortByAsc
        required: false
        in: query
        description: Sorts, in ascending order, the final list by the valid contract field
        schema:
          example: title
          type: string
      - name: sortByDesc
        required: false
        in: query
        description: Sorts, in descending order, the final list by the valid contract field
        schema:
          example: title
          type: string
      - name: externalVendorId
        required: false
        in: query
        description: Filters contracts by External Vendor ID (case-insensitive substring match).
        schema:
          example: vendor-123
          type: string
      - required: true
        name: entityUuid
        description: UUID of the OpenGov entity (typically an agency) the request is acting on
        schema:
          type: string
          format: uuid
        in: path
      responses:
        '200':
          description: A paginated list of contracts was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContractsResponseDto'
        '400':
          description: The request parameters are invalid.
          content:
            application/json:
              examples:
                Invalid `first` parameter (not an integer):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be an integer'
                    error: Bad Request
                Invalid `first` parameter (negative value):
                  value:
                    statusCode: 400
                    message:
                    - '`first` query parameter must be a non-negative number'
                    error: Bad Request
                Malformed `after` cursor:
                  value:
                    statusCode: 400
                    message: Invalid `after` cursor, please only use cursors generated by this API
                    error: Bad Request
                Filtering startDate misordered:
                  value:
                    statusCode: 400
                    message: startDateBefore is earlier than startDateAfter
                    error: Bad Request
                Attempting to sort by invalid field:
                  value:
                    statusCode: 400
                    message: Attemptin

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