openapi: 3.0.3
info:
  title: AbilityOne Procurement List API
  description: >-
    The AbilityOne Procurement List Information Management System (PLIMS) provides
    search access to the AbilityOne Procurement List — the catalog of products and
    services that federal agencies are mandated to procure from nonprofit agencies
    that employ people who are blind or have significant disabilities, under the
    Javits-Wagner-O'Day (JWOD) Act. This spec represents the conceptual API surface
    for the PLIMS system at plims.abilityone.gov.
  version: '1.0.0'
  contact:
    name: US AbilityOne Commission
    url: https://www.abilityone.gov
    email: info@abilityone.gov
  x-generated-from: documentation
externalDocs:
  description: AbilityOne Procurement List
  url: https://www.abilityone.gov/procurement_list/
servers:
  - url: https://plims.abilityone.gov
    description: AbilityOne PLIMS (Procurement List Information Management System)
tags:
  - name: Products
    description: AbilityOne Procurement List products identified by NSN
  - name: Services
    description: AbilityOne Procurement List services
  - name: Agencies
    description: Nonprofit agencies participating in the AbilityOne program
  - name: Reports
    description: Procurement list reports and data downloads
security: []
paths:
  /api/products:
    get:
      operationId: searchProducts
      summary: AbilityOne Search Procurement List Products
      description: >-
        Search the AbilityOne Procurement List for products by National Stock
        Number (NSN), description, agency, or nonprofit affiliate. Returns
        products that federal agencies are mandated to procure through the
        AbilityOne program.
      tags:
        - Products
      parameters:
        - name: nsn
          in: query
          description: National Stock Number (format xxxx-xx-xxx-xxxx)
          schema:
            type: string
            pattern: '^\d{4}-\d{2}-\d{3}-\d{4}$'
          example: "7510-01-234-5678"
        - name: description
          in: query
          description: Product description keyword search (supports wildcards)
          schema:
            type: string
          example: "ballpoint pen"
        - name: nonprofit
          in: query
          description: Filter by nonprofit affiliate (NIB or SourceAmerica)
          schema:
            type: string
            enum:
              - NIB
              - SourceAmerica
          example: "NIB"
        - name: agency
          in: query
          description: Filter by performing nonprofit agency name
          schema:
            type: string
          example: "Lighthouse for the Blind"
        - name: limit
          in: query
          description: Maximum number of results to return
          schema:
            type: integer
            default: 25
            maximum: 100
          example: 25
        - name: offset
          in: query
          description: Pagination offset
          schema:
            type: integer
            default: 0
          example: 0
      responses:
        '200':
          description: Procurement list product search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductSearchResponse'
              examples:
                searchProducts200Example:
                  summary: Default searchProducts 200 response
                  x-microcks-default: true
                  value:
                    total: 48
                    offset: 0
                    limit: 25
                    products:
                      - nsn: "7510-01-234-5678"
                        description: "PEN, BALLPOINT"
                        nonprofitAffiliate: "NIB"
                        performingAgency: "Lighthouse for the Blind - St. Louis"
                        unitOfMeasure: "DZ"
                        approvalDate: "2005-03-15"
                        status: "active"
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/products/{nsn}:
    get:
      operationId: getProduct
      summary: AbilityOne Get Product by NSN
      description: >-
        Retrieve detailed information for a specific AbilityOne Procurement List
        product by its National Stock Number (NSN).
      tags:
        - Products
      parameters:
        - name: nsn
          in: path
          required: true
          description: National Stock Number (format xxxx-xx-xxx-xxxx)
          schema:
            type: string
          example: "7510-01-234-5678"
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
              examples:
                getProduct200Example:
                  summary: Default getProduct 200 response
                  x-microcks-default: true
                  value:
                    nsn: "7510-01-234-5678"
                    description: "PEN, BALLPOINT"
                    longDescription: "Ballpoint pen, retractable, medium point, black ink"
                    nonprofitAffiliate: "NIB"
                    performingAgency: "Lighthouse for the Blind - St. Louis"
                    unitOfMeasure: "DZ"
                    approvalDate: "2005-03-15"
                    status: "active"
                    federalSupplyClass: "7510"
                    productGroupName: "Office Supplies"
        '404':
          description: Product not found on Procurement List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/services:
    get:
      operationId: searchServices
      summary: AbilityOne Search Procurement List Services
      description: >-
        Search the AbilityOne Procurement List for services by type, agency,
        geographic location, or performing nonprofit organization.
      tags:
        - Services
      parameters:
        - name: serviceType
          in: query
          description: Type of service
          schema:
            type: string
            enum:
              - Custodial
              - Grounds Maintenance
              - Food Service
              - Laundry
              - Administrative
              - Mailroom
              - Document Destruction
              - IT Support
          example: "Custodial"
        - name: state
          in: query
          description: State where service is performed (2-letter abbreviation)
          schema:
            type: string
            maxLength: 2
          example: "VA"
        - name: nonprofit
          in: query
          description: Filter by nonprofit affiliate
          schema:
            type: string
            enum:
              - NIB
              - SourceAmerica
          example: "SourceAmerica"
        - name: limit
          in: query
          schema:
            type: integer
            default: 25
          example: 25
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          example: 0
      responses:
        '200':
          description: Procurement list service search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceSearchResponse'
              examples:
                searchServices200Example:
                  summary: Default searchServices 200 response
                  x-microcks-default: true
                  value:
                    total: 12
                    offset: 0
                    limit: 25
                    services:
                      - id: "svc-00123"
                        serviceType: "Custodial"
                        description: "Custodial services at federal building"
                        location: "Pentagon, Arlington, VA"
                        state: "VA"
                        nonprofitAffiliate: "SourceAmerica"
                        performingAgency: "SERVICEMASTER"
                        approvalDate: "2010-06-01"
                        status: "active"
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/agencies:
    get:
      operationId: listAgencies
      summary: AbilityOne List Nonprofit Agencies
      description: >-
        Retrieve a list of nonprofit agencies participating in the AbilityOne
        program, optionally filtered by affiliate (NIB or SourceAmerica) or state.
      tags:
        - Agencies
      parameters:
        - name: affiliate
          in: query
          description: Filter by central nonprofit agency affiliate
          schema:
            type: string
            enum:
              - NIB
              - SourceAmerica
          example: "NIB"
        - name: state
          in: query
          description: Filter by state (2-letter abbreviation)
          schema:
            type: string
            maxLength: 2
          example: "TX"
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          example: 50
      responses:
        '200':
          description: List of participating nonprofit agencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgencyListResponse'
              examples:
                listAgencies200Example:
                  summary: Default listAgencies 200 response
                  x-microcks-default: true
                  value:
                    total: 93
                    agencies:
                      - id: "agency-001"
                        name: "Lighthouse for the Blind - St. Louis"
                        affiliate: "NIB"
                        state: "MO"
                        city: "St. Louis"
                        phone: "314-842-1180"
                        website: "https://www.blindmissouri.org"
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/reports/products:
    get:
      operationId: downloadProductReport
      summary: AbilityOne Download Products List Report
      description: >-
        Download the complete AbilityOne Procurement List products report in
        Excel or CSV format, containing all NSN-identified products with
        performing agency and unit details.
      tags:
        - Reports
      parameters:
        - name: format
          in: query
          description: Report output format
          schema:
            type: string
            enum:
              - excel
              - csv
            default: excel
          example: "excel"
        - name: affiliate
          in: query
          description: Filter by nonprofit affiliate
          schema:
            type: string
            enum:
              - NIB
              - SourceAmerica
          example: "NIB"
      responses:
        '200':
          description: Products list report file
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid format parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

  /api/reports/services:
    get:
      operationId: downloadServiceReport
      summary: AbilityOne Download Services List Report
      description: >-
        Download the complete AbilityOne Procurement List services report in
        Excel or CSV format, containing all services with location, performing
        agency, and service type details.
      tags:
        - Reports
      parameters:
        - name: format
          in: query
          description: Report output format
          schema:
            type: string
            enum:
              - excel
              - csv
            default: excel
          example: "excel"
      responses:
        '200':
          description: Services list report file
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema:
                type: string
                format: binary
            text/csv:
              schema:
                type: string
        '400':
          description: Invalid format parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK

components:
  schemas:
    Product:
      type: object
      description: An AbilityOne Procurement List product identified by National Stock Number
      properties:
        nsn:
          type: string
          description: National Stock Number (primary identifier)
          example: "7510-01-234-5678"
        description:
          type: string
          description: Short product description
          example: "PEN, BALLPOINT"
        longDescription:
          type: string
          description: Detailed product description
          example: "Ballpoint pen, retractable, medium point, black ink"
        nonprofitAffiliate:
          type: string
          description: Central nonprofit agency affiliate (NIB or SourceAmerica)
          enum:
            - NIB
            - SourceAmerica
          example: "NIB"
        performingAgency:
          type: string
          description: Name of the nonprofit agency producing the product
          example: "Lighthouse for the Blind - St. Louis"
        unitOfMeasure:
          type: string
          description: Unit of measure for ordering
          example: "DZ"
        unitPrice:
          type: number
          description: Unit price in USD
          example: 4.85
        approvalDate:
          type: string
          format: date
          description: Date product was added to the Procurement List
          example: "2005-03-15"
        status:
          type: string
          description: Product status on the Procurement List
          enum:
            - active
            - deleted
          example: "active"
        federalSupplyClass:
          type: string
          description: Federal Supply Class (FSC) code
          example: "7510"
        productGroupName:
          type: string
          description: Product group or category name
          example: "Office Supplies"

    ProductSearchResponse:
      type: object
      description: Paginated search results for Procurement List products
      properties:
        total:
          type: integer
          description: Total matching products
          example: 48
        offset:
          type: integer
          description: Pagination offset
          example: 0
        limit:
          type: integer
          description: Page size
          example: 25
        products:
          type: array
          description: List of matching products
          items:
            $ref: '#/components/schemas/Product'

    Service:
      type: object
      description: An AbilityOne Procurement List service
      properties:
        id:
          type: string
          description: Service identifier
          example: "svc-00123"
        serviceType:
          type: string
          description: Type of service
          example: "Custodial"
        description:
          type: string
          description: Service description
          example: "Custodial services at federal building"
        location:
          type: string
          description: Location where service is performed
          example: "Pentagon, Arlington, VA"
        state:
          type: string
          description: State abbreviation
          example: "VA"
        nonprofitAffiliate:
          type: string
          description: Central nonprofit affiliate
          enum:
            - NIB
            - SourceAmerica
          example: "SourceAmerica"
        performingAgency:
          type: string
          description: Name of nonprofit agency performing the service
          example: "SERVICEMASTER"
        approvalDate:
          type: string
          format: date
          description: Date service was added to the Procurement List
          example: "2010-06-01"
        status:
          type: string
          description: Service status
          enum:
            - active
            - deleted
          example: "active"

    ServiceSearchResponse:
      type: object
      description: Paginated search results for Procurement List services
      properties:
        total:
          type: integer
          example: 12
        offset:
          type: integer
          example: 0
        limit:
          type: integer
          example: 25
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'

    Agency:
      type: object
      description: A nonprofit agency participating in the AbilityOne program
      properties:
        id:
          type: string
          description: Agency identifier
          example: "agency-001"
        name:
          type: string
          description: Agency name
          example: "Lighthouse for the Blind - St. Louis"
        affiliate:
          type: string
          description: Central nonprofit affiliate
          enum:
            - NIB
            - SourceAmerica
          example: "NIB"
        state:
          type: string
          description: State abbreviation
          example: "MO"
        city:
          type: string
          description: City
          example: "St. Louis"
        address:
          type: string
          description: Mailing address
          example: "4244 Forest Park Ave, St. Louis, MO 63108"
        phone:
          type: string
          description: Contact phone number
          example: "314-842-1180"
        website:
          type: string
          description: Agency website URL
          example: "https://www.blindmissouri.org"
        employeesBlind:
          type: integer
          description: Number of employees who are blind
          example: 125
        employeesDisabled:
          type: integer
          description: Number of employees with significant disabilities
          example: 45

    AgencyListResponse:
      type: object
      description: List of nonprofit agencies
      properties:
        total:
          type: integer
          example: 93
        agencies:
          type: array
          items:
            $ref: '#/components/schemas/Agency'

    APIError:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error code
          example: "not_found"
        message:
          type: string
          description: Human-readable error message
          example: "NSN not found on Procurement List."
        code:
          type: integer
          description: HTTP status code
          example: 404