{
  "openapi": "3.1.0",
  "info": {
    "title": "HPH Integrations material vendor directory candidate",
    "version": "v1",
    "description": "HPH Integrations public API v1. Available to the Customer Testing group; not available in Production."
  },
  "paths": {
    "/v1/vendors": {
      "get": {
        "operationId": "ListMaterialVendors",
        "x-runtime-status": "testing-available",
        "responses": {
          "200": {
            "description": "The represented company's bounded material vendor directory.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/MaterialVendorCollectionResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "evaluated_at": "2026-10-29T16:00:00Z",
                  "vendors": [
                    {
                      "vendor_skey": "vendor-syn-001",
                      "code": "SYN",
                      "name": "Synthetic Supply Company",
                      "vendor_type": "Material Supplier",
                      "status": "active",
                      "transaction_pipeline_available": true,
                      "logo_url": "https://assets.example.test/vendor.png",
                      "branch_location": "Cincinnati Main Branch",
                      "address": {
                        "address_1": "123 Main Street", "address_2": null, "address_3": null,
                        "city": "Cincinnati", "state": "OH", "postal_code": "45202"
                      },
                      "contact": {
                        "telephone": "555-555-0100", "quote_request_email": "quotes@example.test",
                        "website": "https://example.test"
                      },
                      "account_count": 2
                    }
                  ],
                  "vendor_count": 1
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/CollectionLimitExceeded" },
          "429": { "$ref": "#/components/responses/QuotaExceeded" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/v1/vendors/{vendor_skey}/accounts": {
      "get": {
        "operationId": "ListMaterialVendorAccounts",
        "x-runtime-status": "testing-available",
        "parameters": [
          {
            "name": "vendor_skey",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 1, "maxLength": 255 },
            "description": "The stable opaque vendor identity returned by GET /v1/vendors."
          }
        ],
        "responses": {
          "200": {
            "description": "The complete bounded active-account collection for a represented-company vendor.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/VendorAccountCollectionResponseV1" },
                "example": {
                  "contract_version": "v1",
                  "evaluated_at": "2026-11-04T14:00:00Z",
                  "vendor_skey": "vendor-syn-001",
                  "accounts": [
                    {
                      "vendor_account_skey": "vendor-account-syn-001",
                      "account_number": "123456",
                      "name": "Main Purchasing Account"
                    }
                  ],
                  "account_count": 1
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "409": { "$ref": "#/components/responses/CollectionLimitExceeded" },
          "429": { "$ref": "#/components/responses/QuotaExceeded" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MaterialVendorCollectionResponseV1": {
        "type": "object", "additionalProperties": false,
        "required": ["contract_version", "evaluated_at", "vendors", "vendor_count"],
        "properties": {
          "contract_version": { "type": "string", "const": "v1" },
          "evaluated_at": { "type": "string", "format": "date-time" },
          "vendors": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MaterialVendorV1" } },
          "vendor_count": { "type": "integer", "minimum": 0, "maximum": 50 }
        }
      },
      "MaterialVendorV1": {
        "type": "object", "additionalProperties": false,
        "required": ["vendor_skey", "name", "vendor_type", "status", "transaction_pipeline_available", "logo_url", "branch_location", "address", "contact", "account_count"],
        "properties": {
          "vendor_skey": { "type": "string", "minLength": 1, "maxLength": 255 },
          "code": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
          "name": { "type": "string", "minLength": 1, "maxLength": 255 },
          "vendor_type": { "type": "string", "minLength": 1, "maxLength": 255 },
          "status": { "type": "string", "const": "active" },
          "transaction_pipeline_available": { "type": "boolean" },
          "logo_url": { "type": ["string", "null"], "format": "uri", "maxLength": 2048 },
          "branch_location": { "type": ["string", "null"], "maxLength": 255 },
          "address": { "$ref": "#/components/schemas/VendorAddressV1" },
          "contact": { "$ref": "#/components/schemas/VendorContactV1" },
          "account_count": { "type": "integer", "minimum": 0 }
        }
      },
      "VendorAddressV1": {
        "type": "object", "additionalProperties": false,
        "required": ["address_1", "address_2", "address_3", "city", "state", "postal_code"],
        "properties": {
          "address_1": { "type": ["string", "null"], "maxLength": 255 }, "address_2": { "type": ["string", "null"], "maxLength": 255 },
          "address_3": { "type": ["string", "null"], "maxLength": 255 }, "city": { "type": ["string", "null"], "maxLength": 255 },
          "state": { "type": ["string", "null"], "maxLength": 255 }, "postal_code": { "type": ["string", "null"], "maxLength": 255 }
        }
      },
      "VendorContactV1": {
        "type": "object", "additionalProperties": false,
        "required": ["telephone", "quote_request_email", "website"],
        "properties": {
          "telephone": { "type": ["string", "null"], "maxLength": 255 },
          "quote_request_email": { "type": ["string", "null"], "maxLength": 255 },
          "website": { "type": ["string", "null"], "format": "uri", "maxLength": 2048 }
        }
      },
      "VendorAccountCollectionResponseV1": {
        "type": "object", "additionalProperties": false,
        "required": ["contract_version", "evaluated_at", "vendor_skey", "accounts", "account_count"],
        "properties": {
          "contract_version": { "type": "string", "const": "v1" },
          "evaluated_at": { "type": "string", "format": "date-time" },
          "vendor_skey": { "type": "string", "minLength": 1, "maxLength": 255 },
          "accounts": {
            "type": "array", "maxItems": 50,
            "items": { "$ref": "#/components/schemas/VendorAccountV1" }
          },
          "account_count": { "type": "integer", "minimum": 0, "maximum": 50 }
        }
      },
      "VendorAccountV1": {
        "type": "object", "additionalProperties": false,
        "required": ["vendor_account_skey", "account_number", "name"],
        "properties": {
          "vendor_account_skey": { "type": "string", "minLength": 1, "maxLength": 255 },
          "account_number": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
          "name": { "type": "string", "minLength": 1, "maxLength": 255 }
        }
      },
      "StableProblemV1": { "type": "object", "additionalProperties": false, "required": ["type", "title", "status", "code", "correlation_id", "retryable", "errors"], "description": "Problem details as sent on the wire (application/problem+json). Field names are snake_case, like every other request and response body.", "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string" }, "correlation_id": { "type": "string" }, "retryable": { "type": "boolean" }, "errors": { "type": ["object", "null"], "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }
    },
    "responses": {
      "BadRequest": { "description": "Invalid vendor identity or request shape.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "Unauthorized": { "description": "Authentication failed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "Forbidden": { "description": "Current Enterprise and represented-company authority are required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "NotFound": { "description": "The represented company or selected vendor was not found or is concealed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "CollectionLimitExceeded": { "description": "The provider response declares or contains more than the v1 maximum; no additional partial list is returned.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "QuotaExceeded": { "description": "The represented company's vendor-directory quota is unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } },
      "Unavailable": { "description": "The authoritative vendor source is unavailable.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/StableProblemV1" } } } }
    }
  }
}