OpenGov Purchase Order API

openapi: 3.2.0
info:
  title: OpenGov Purchase Order API
  version: 1.0.0
  description: API for managing purchase orders, line items, splits, and vendors.
servers:
- url: https://api-purchase-order.procurement.opengov.com
  description: Production
- url: https://api-purchase-order.procurement.ogstaging.us
  description: Staging
- url: https://api-purchase-order.procurement.ogintegration.us
  description: Integration
security:
- platformApiKey: []
- platformBearerToken: []
tags:
- name: purchaseOrder
paths:
  /api/v1/po/entities/{entityId}/purchase-orders/{id}:
    get:
      tags:
      - purchaseOrder
      operationId: purchaseOrder.findById
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
        description: The UUID of the Platform entity
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      - name: revision
        in: query
        schema:
          $ref: '#/components/schemas/PoRevisionParam'
        required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - purchaseOrder
                    properties:
                      purchaseOrder:
                        type: object
                        required:
                        - id
                        - govId
                        - poNumber
                        - status
                        - poType
                        - source
                        - vendor
                        - lineItems
                        - createdAt
                        - createdBy
                        - updatedAt
                        - updatedBy
                        - organizationUnit
                        - canInitiateChangeOrder
                        - pendingCoId
                        - pendingCoNumber
                        - changeOrders
                        properties:
                          id:
                            type: number
                          govId:
                            type: number
                          poNumber:
                            type: string
                            description: a string at most 32 character(s) long
                            title: maxLength(32)
                            maxLength: 32
                          status:
                            $ref: '#/components/schemas/PoStatus'
                          totalAmount:
                            anyOf:
                            - $ref: '#/components/schemas/SignedDecimal_18_2'
                            - type: 'null'
                          poType:
                            $ref: '#/components/schemas/PoType'
                          poDate:
                            anyOf:
                            - $ref: '#/components/schemas/ISODate'
                            - type: 'null'
                          fiscalYear:
                            anyOf:
                            - type: number
                            - type: 'null'
                          fiscalPeriod:
                            anyOf:
                            - type: number
                            - type: 'null'
                          description:
                            anyOf:
                            - type: string
                            - type: 'null'
                          attentionTo:
                            anyOf:
                            - type: string
                            - type: 'null'
                          referenceNumber:
                            anyOf:
                            - type: string
                            - type: 'null'
                          requiredDate:
                            anyOf:
                            - $ref: '#/components/schemas/ISODate'
                            - type: 'null'
                          paymentTermId:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          paymentTermCode:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          paymentTermDesc:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          periodOfConformanceFrom:
                            anyOf:
                            - $ref: '#/components/schemas/ISODate'
                            - type: 'null'
                          periodOfConformanceTo:
                            anyOf:
                            - $ref: '#/components/schemas/ISODate'
                            - type: 'null'
                          requestorId:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          purchaserId:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          departmentId:
                            anyOf:
                            - type: number
                            - type: 'null'
                          departmentName:
                            anyOf:
                            - type: string
                              description: a string at most 128 character(s) long
                              title: maxLength(128)
                              maxLength: 128
                            - type: 'null'
                          source:
                            $ref: '#/components/schemas/PoSource'
                          purchaseRequestId:
                            anyOf:
                            - type: number
                            - type: 'null'
                          prAmount:
                            anyOf:
                            - $ref: '#/components/schemas/Decimal_18_2'
                            - type: 'null'
                          contractId:
                            anyOf:
                            - type: number
                            - type: 'null'
                          contractNumber:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          purchaseRequestNumber:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          shipToAddressLine1:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToAddressLine2:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToCity:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToState:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToZip:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToDeliveryCode:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToDeliveryCodeId:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToLocationName:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToLocationType:
                            anyOf:
                            - type: string
                            - type: 'null'
                          shipToCountryCode:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToAddressLine1:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToAddressLine2:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToCity:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToState:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToZip:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToDeliveryCode:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToDeliveryCodeId:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToLocationName:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToLocationType:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToCountryCode:
                            anyOf:
                            - type: string
                            - type: 'null'
                          billToSameAsShipTo:
                            type: boolean
                          encumberedAmount:
                            $ref: '#/components/schemas/Decimal_18_2'
                          matchedAmount:
                            $ref: '#/components/schemas/SignedDecimal_18_2'
                          invoicedAmount:
                            $ref: '#/components/schemas/SignedDecimal_18_2'
                          paidAmount:
                            $ref: '#/components/schemas/SignedDecimal_18_2'
                          encLiquidatedAccrualAmount:
                            $ref: '#/components/schemas/SignedDecimal_18_2'
                          availableAmount:
                            $ref: '#/components/schemas/SignedDecimal_18_2'
                          openEncumbranceAmount:
                            anyOf:
                            - $ref: '#/components/schemas/SignedDecimal_18_2'
                            - type: 'null'
                          label:
                            anyOf:
                            - type: string
                              description: a string at most 50 character(s) long
                              title: maxLength(50)
                              maxLength: 50
                            - type: 'null'
                          submittedAt:
                            anyOf:
                            - type: string
                            - type: 'null'
                          approvedAt:
                            anyOf:
                            - type: string
                            - type: 'null'
                          rejectedAt:
                            anyOf:
                            - type: string
                            - type: 'null'
                          issuedAt:
                            anyOf:
                            - type: string
                            - type: 'null'
                          cancelledAt:
                            anyOf:
                            - type: string
                            - type: 'null'
                          closedAt:
                            anyOf:
                            - type: string
                            - type: 'null'
                          submittedBy:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          approvedBy:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          rejectedBy:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          issuedBy:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          cancelledBy:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          revision:
                            type: number
                          hasPendingCo:
                            type: boolean
                          orgUnitUuid:
                            anyOf:
                            - type: string
                              description: a Universally Unique Identifier
                              format: uuid
                              pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                            - type: 'null'
                          hasTolerance:
                            anyOf:
                            - type: boolean
                            - type: 'null'
                          vendor:
                            anyOf:
                            - $ref: '#/components/schemas/VendorModel.json'
                            - type: 'null'
                          lineItems:
                            type: array
                            items:
                              anyOf:
                              - $ref: '#/components/schemas/LineItemModel.json'
                              - type: 'null'
                          createdAt:
                            $ref: '#/components/schemas/DateTimeUtc'
                          createdBy:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                          updatedAt:
                            $ref: '#/components/schemas/DateTimeUtc'
                          updatedBy:
                            type: string
                            description: a Universally Unique Identifier
                            format: uuid
                            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                          organizationUnit:
                            anyOf:
                            - type: object
                              required:
                              - id
                              - uuid
                              - name
                              properties:
                                id:
                                  anyOf:
                                  - type: number
                                  - $ref: '#/components/schemas/NumberFromString'
                                uuid:
                                  type: string
                                  description: a Universally Unique Identifier
                                  format: uuid
                                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                                name:
                                  type: string
                                code:
                                  anyOf:
                                  - anyOf:
                                    - type: string
                                    - type: number
                                  - type: 'null'
                                description:
                                  anyOf:
                                  - type: string
                                  - type: 'null'
                                isPrimary:
                                  type: boolean
                                active:
                                  type: boolean
                              additionalProperties: false
                            - type: 'null'
                          canInitiateChangeOrder:
                            type: boolean
                          pendingCoId:
                            anyOf:
                            - type: number
                            - type: 'null'
                          pendingCoNumber:
                            anyOf:
                            - type: string
                            - type: 'null'
                          changeOrders:
                            type: array
                            items:
                              type: object
                              required:
                              - id
                              - coNumber
                              - status
                              - changeInTotal
                              - approvedAt
                              properties:
                                id:
                                  type: number
                                coNumber:
                                  type: string
                                status:
                                  type: string
                                changeInTotal:
                                  anyOf:
                                  - type: string
                                  - type: 'null'
                                approvedAt:
                                  anyOf:
                                  - type: string
                                  - type: 'null'
                              additionalProperties: false
                        additionalProperties: false
                    additionalProperties: false
                additionalProperties: false
        '400':
          description: The request did not match the expected schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 400
                  code:
                    type: string
                    description: Machine-readable error code
                    example: ValidationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: The request body failed validation.
                  fieldErrors:
                    type: array
                    description: Per-field validation errors (present for 400 validation errors)
                    items:
                      type: object
                      properties:
                        parameter:
                          type: string
                          description: Dot-path to the field
                          example: lineItems.0.lineItemSplits.1
                        detail:
                          type: string
                          description: Human-readable validation message
                          example: 'Account 101-5100 has insufficient budget: requested 500.00, available 200.00'
                        code:
                          type: string
                          description: Machine-readable rule identifier
                          example: BUDGET_INSUFFICIENT
                        data:
                          type: object
                          description: Structured context for the error (account codes, amounts, IDs, etc.)
                          additionalProperties: true
                          example:
                            accountNumber: 101-5100
                            accountPseudoKey: GF-101-5100
                            requestedAmount: 500
                            availableAmount: 200
                      required:
                      - parameter
                      - detail
                required:
                - status
                - code
                - detail
        '401':
          description: AuthError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 401
                  code:
                    type: string
                    description: Machine-readable error code
                    example: AuthenticationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: Authentication is required to access this resource.
                required:
                - status
                - code
                - detail
        '403':
          description: UnauthorizedError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 403
                  code:
                    type: string
                    description: Machine-readable error code
                    example: AuthorizationError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: You do not have permission to perform this action.
                required:
                - status
                - code
                - detail
        '404':
          description: EntityNotFoundError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 404
                  code:
                    type: string
                    description: Machine-readable error code
                    example: PurchaseOrderNotFound
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: Purchase order with id 123 was not found.
                required:
                - status
                - code
                - detail
        '500':
          description: InfrastructureError
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    description: HTTP status code
                    example: 500
                  code:
                    type: string
                    description: Machine-readable error code
                    example: InternalServerError
                  detail:
                    type: string
                    description: Human-readable error description. For 400 ValidationError with exactly one field issue, matches that field's `detail`; otherwise a summary (e.g. multiple validation issues).
                    example: An unexpected error occurred while processing your request. Please try again later.
                required:
                - status
                - code
                - detail
      description: Retrieve a purchase order by ID with vendor, line items, and splits. Pass `?revision=N` to return a historical snapshot rebuilt from po_revision_history. When omitted, the current PO is returned. When `revision` matches the current PO revision, the current PO is returned (no snapshot lookup). When `revision=0` and the PO has no revision history, the current PO is returned. Otherwise a missing snapshot row produces 404 PoRevisionNotFoundError.
      summary: Find Purchase Order by ID
    put:
      tags:
      - purchaseOrder
      operationId: purchaseOrder.update
      parameters:
      - name: entityId
        in: path
        schema:
          type: string
          description: The UUID of the Platform entity
          default: 04eb277c-f9cd-42b0-9610-0f068f6aaea1
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        required: true
        description: The UUID of the Platform entity
      - name: id
        in: path
        schema:
          $ref: '#/components/schemas/NumberFromString'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: object
                    required:
                    - purchaseOrder
                    properties:
                      purchaseOrder:
                        type: object
                        required:
                        - id
                        - govId
                        - poNumber
                        - status
                        - poType
                        - source
                        - vendor
                        - lineItems
                        - createdAt
                        - createdBy
                        - updatedAt
                        - updatedBy
                        - organizationUnit
                        - canInitiateChangeOrder
                        - pendingCoId
                        - pendingCoNumber
                        - changeOrders
                        properties:
                          id:
                            type: number
                          govId:
                            type: number
                          poNumber:
                            type: string
                            description: a string at most 32 character(s) long
                            title: maxLength(32)
                            maxLength: 32
                          status:
                            $ref: '#/components/schemas/PoStatus'
                          totalAmount:
                            anyOf:
                            - $ref: '#/components/schemas/SignedDecimal_18_2'
                            - type: 'null'
                          poType:
                            $ref: '#/components/schemas/PoType'
                          poDate:
                            anyOf:
                            - $ref: '#/components/schemas/ISODate'
                            - type: 'null'
                          fiscalYear:
                            anyOf:
                            - type: number
                            - type: 'null'
                          fiscalPeriod:
                            anyOf:
                            - type: number
                            - type: 'null'
                          description:
                            anyOf:
                            - type: string
                            - type: 'null'
                          attentionTo:
                            anyOf:
                            - type: string
                            - type: 'null'
                          referenceNumber:
                            anyOf:
                            - type: string
                            - type: 'null'
                          requiredDate:
                            anyOf:
                            - $ref: '#/components/schemas/ISODate'
                            - type: 'null'
                          paymentTermId:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          paymentTermCode:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                              maxLength: 255
                            - type: 'null'
                          paymentTermDesc:
                            anyOf:
                            - type: string
                              description: a string at most 255 character(s) long
                              title: maxLength(255)
                         

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