openapi: 3.0.3
info:
  title: Zuper REST Assets Purchase Orders API
  description: The Zuper REST API provides programmatic access to the Zuper field service management platform. It covers jobs, scheduling, route optimization, customers, organizations, assets, inventory, purchase orders, invoices, proposals, quotes, timesheets, projects, properties, service tasks, service contracts, webhooks, and communications. Authentication uses API keys passed via the x-api-key header. Region-specific base URLs are discovered by POSTing to the accounts endpoint.
  version: 1.0.0
  contact:
    name: Zuper Developer Support
    url: https://developers.zuper.co/discuss
  x-api-evangelist-ratings:
    design: 7
    consistency: 7
    documentation: 8
servers:
- url: https://{dc_region}.zuperpro.com/api
  description: Region-specific API server (dc_region obtained from accounts endpoint)
  variables:
    dc_region:
      default: us1
      description: Data-center region identifier returned by the config endpoint
- url: https://accounts.zuperpro.com/api
  description: Accounts / configuration endpoint
security:
- ApiKeyAuth: []
tags:
- name: Purchase Orders
  description: Vendor purchase order management
paths:
  /purchase_orders:
    get:
      summary: Get Purchase Orders
      operationId: getPurchaseOrders
      description: Retrieve a paginated list of purchase orders.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/CountParam'
      - $ref: '#/components/parameters/SortParam'
      responses:
        '200':
          description: Paginated list of purchase orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
    post:
      summary: Create Purchase Order
      operationId: createPurchaseOrder
      description: Create a new purchase order.
      tags:
      - Purchase Orders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Purchase order created successfully
        '400':
          description: Bad request
  /purchase_orders/{purchase_order_uid}:
    get:
      summary: Get Purchase Order Details
      operationId: getPurchaseOrderDetails
      description: Retrieve details of a specific purchase order.
      tags:
      - Purchase Orders
      parameters:
      - name: purchase_order_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Purchase order details
        '404':
          description: Not found
    put:
      summary: Update Purchase Order
      operationId: updatePurchaseOrder
      description: Update an existing purchase order.
      tags:
      - Purchase Orders
      parameters:
      - name: purchase_order_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated successfully
        '400':
          description: Bad request
    delete:
      summary: Delete Purchase Order
      operationId: deletePurchaseOrder
      description: Delete a purchase order.
      tags:
      - Purchase Orders
      parameters:
      - name: purchase_order_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted successfully
        '404':
          description: Not found
  /purchase_orders/{purchase_order_uid}/send:
    post:
      summary: Send Purchase Order
      operationId: sendPurchaseOrder
      description: Send a purchase order to the vendor.
      tags:
      - Purchase Orders
      parameters:
      - name: purchase_order_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Purchase order sent successfully
  /purchase_orders/{purchase_order_uid}/status:
    put:
      summary: Update Purchase Order Status
      operationId: updatePurchaseOrderStatus
      description: Update the status of a purchase order.
      tags:
      - Purchase Orders
      parameters:
      - name: purchase_order_uid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
      responses:
        '200':
          description: Status updated successfully
components:
  parameters:
    CountParam:
      name: count
      in: query
      description: Number of records per page (max 1000)
      schema:
        type: integer
        default: 10
        maximum: 1000
    SortParam:
      name: sort
      in: query
      schema:
        type: string
        enum:
        - DESC
        - ASC
        default: DESC
    PageParam:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        default: 1
  schemas:
    PaginatedResponse:
      type: object
      properties:
        type:
          type: string
        total_records:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key generated from Zuper Settings > Developer Hub > API Keys