Skip to main content

Matrix API

The Matrix API allows you to retrieve competitive comparison matrices. Matrices visualize how competitors compare across different categories and capabilities. The API supports both category-level (detailed) and solution-level (strategic) matrix views.

Note: Matrix view requires PRO plan or higher.

Get Matrix​

Fetch matrix data for visualization.

GET /api/matrix?productId={productId}&competitorIds={id1,id2}&includeOurProduct=true

Query Parameters​

  • productId (string, optional) - Filter competitors by product. Also required if includeOurProduct is true
  • competitorIds (string, optional) - Comma-separated list of competitor IDs to include
  • includeOurProduct (boolean, optional) - Include "our product" column with capabilities. Requires productId. Defaults to false

Response​

{
  "categories": [
    {
      "id": "pricing",
      "name": "Pricing"
    },
    {
      "id": "features",
      "name": "Features"
    }
  ],
  "competitors": [
    {
      "id": "competitor-id-1",
      "name": "Competitor Inc",
      "status": "COMPLETE"
    },
    {
      "id": "competitor-id-2",
      "name": "Another Competitor",
      "status": "COMPLETE"
    }
  ],
  "cells": [
    {
      "id": "cell-id",
      "workspaceId": "workspace-id",
      "competitorId": "competitor-id-1",
      "productId": "product-id",
      "categoryId": "pricing",
      "summary": ["Competitor has competitive pricing"],
      "capabilityStatus": "MATCH"
    }
  ],
  "cellMap": {
    "pricing": {
      "competitor-id-1": {
        "id": "cell-id",
        "workspaceId": "workspace-id",
        "competitorId": "competitor-id-1",
        "productId": "product-id",
        "categoryId": "pricing",
        "summary": ["Competitor has competitive pricing"],
        "capabilityStatus": "MATCH"
      }
    }
  },
  "ourProduct": {
    "productId": "product-id",
    "capabilities": {
      "pricing": {
        "summary": ["We offer flexible pricing"],
        "capabilityStatus": "SUPERIOR"
      }
    }
  }
}

Capability Status Values​

  • SUPERIOR - Our product is superior in this category
  • MATCH - Our product matches the competitor
  • INFERIOR - Our product is inferior in this category
  • UNKNOWN - Status is unknown

Response Fields​

  • categories - Array of category objects with id and name
  • competitors - Array of competitor objects with id, name, and status
  • cells - Array of all matrix cells
  • cellMap - Object mapping categoryId → competitorId → cell for easy lookup
  • ourProduct - Object containing our product capabilities (only included if includeOurProduct=true)

Category Priority​

Categories are determined in this priority order:

  1. Product categories (if productId is provided)
  2. Competitor categories (from first competitor)
  3. Matrix cell categories
  4. Default categories

Get Solution Matrix​

Fetch solution matrix data for high-level strategic comparison. Solutions span multiple products and aggregate category scores.

GET /api/matrix/solutions?competitorIds={id1,id2}&solutionIds={id1,id2}

Query Parameters​

  • competitorIds (string, optional) - Comma-separated list of competitor IDs to include
  • solutionIds (string, optional) - Comma-separated list of solution IDs to filter by

Response​

{
  "solutions": [
    {
      "id": "solution-id-1",
      "name": "Enterprise Security",
      "description": "Comprehensive security and compliance capabilities",
      "productIds": ["product-id-1", "product-id-2"],
      "categoryMappings": [
        {
          "categoryId": "security",
          "productId": "product-id-1",
          "weight": 0.5
        }
      ]
    }
  ],
  "competitors": [
    {
      "id": "competitor-id-1",
      "name": "Competitor Inc",
      "status": "READY"
    }
  ],
  "cells": [
    {
      "id": "solution-cell-id",
      "workspaceId": "workspace-id",
      "solutionId": "solution-id-1",
      "competitorId": "competitor-id-1",
      "aggregatedScore": 3.5,
      "contributingCategoryIds": ["matrix-cell-id-1", "matrix-cell-id-2"],
      "evidenceIds": ["intel-id-1"],
      "lastRefreshedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "cellMap": {
    "solution-id-1": {
      "competitor-id-1": { ...solutionMatrixCell }
    }
  },
  "categoryCellMap": {
    "category-id-1": {
      "competitor-id-1": { ...matrixCell }
    }
  }
}

Response Fields​

  • solutions - Array of solution objects with category mappings
  • competitors - Array of competitor objects
  • cells - Array of solution matrix cells (aggregated scores)
  • cellMap - Object mapping solutionId → competitorId → solution cell
  • categoryCellMap - Object mapping categoryId → competitorId → category cell (for drill-down)

Aggregated Score​

The aggregatedScore field (0-4) represents a Harvey Ball level calculated from weighted category scores:

  • 4 = Full (Native/Excellent)
  • 3 = 3/4 (Good)
  • 2 = Half (Parity/Average)
  • 1 = 1/4 (Weak)
  • 0 = Empty (Missing)

Drill-Down Capability​

Use categoryCellMap to drill down from solution-level scores to underlying category-level details. The contributingCategoryIds field lists the matrix cell IDs that contributed to the aggregated score.

Error Responses​

  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (requires PRO plan or higher)
  • 404 - Not Found (product or competitor doesn't exist)

Plan Requirement Error​

If you're on a plan that doesn't support matrices, you'll receive a 403 error:

{
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "Competitor matrices are available on PRO plan and above. Upgrade to compare competitors visually.",
    "requiredPlan": "PRO"
  }
}