API reference / Risk

List Risk Findings

MD View as MarkdownPlain text version of this page

Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page

GET /api/v1/risk/findings

Token needs the read ability. About tokens

Risk Assessment flags: stores whose discount rate or $0-check rate is outside their usual range, each with the plain-sentence factors the Risk drill-down shows. By default returns unresolved findings (open or acknowledged), worst tier first and, within a tier, longest-running first. Requires the read ability, the Risk Assessment feature, and the view risk assessment permission; a franchisee token additionally needs risk to be visible to franchisees.

Franchisee tokens see only their own stores' findings, receive no tier, peak_tier, or escalation (every flag reads "Outside your usual range" in tier_label), and never receive network findings. The same report backs the get-risk-findings MCP tool.

Query parameters

location string (uuid)

Location UUID. Adds latest_assessment for each rate the account scores to the response. A franchisee token asking for a location outside its portfolio receives 403.
metric string

One rate. cash_share is scored only where the account has cash share turned on; it is flagged when the store's cash share falls well below its own norm.

discount_rate zero_net_check_rate cash_share
status string

One status, or any. Default open and acknowledged.

open acknowledged explained cleared any
min_tier string

Findings at or above this tier. Ignored for franchisee tokens.

watch elevated high
opened_since string (date)

Only findings opened on or after this date, formatted YYYY-MM-DD.
include_network boolean

Franchisor tokens only: also return network_findings, where much of the network moved together. Ignored for franchisee tokens.
limit integer

Maximum findings to return (1–100, default 25).

Responses

- data RiskFindings
  - latest_assessed_on string (date) nullable
    
    The latest night the engine assessed; null before its first run.
  - count integer
    
    Findings in this response.
  - total integer
    
    Findings matching the filters before the limit.
  - summary RiskFindingsSummary
    
    Counts over every finding matching the filters, before the limit. Tier counts are omitted for franchisee tokens.
    
    findings integer
    
    stores integer
    
    Distinct stores with at least one matching finding.
    
    by_metric object
    
    Keyed by metric (discount_rate, zero_net_check_rate, cash_share).
    
    by_tier object
    
    Franchisor only; keyed by tier (high, elevated, watch).
    
    stores_on_both_metrics object
    
    Stores with a matching finding on both rates.
    
    count integer
    
    stores array of string
  - findings array of RiskFinding
    
    id string (uuid)
    
    location object
    
    uuid string (uuid)
    
    name string
    
    district string nullable
    
    category string nullable
    
    metric string
    
    discount_rate zero_net_check_rate cash_share
    
    metric_label string
    
    kind string
    
    spike chronic drift hard_threshold
    
    kind_label string
    
    tier string
    
    Omitted for franchisee tokens.
    
    watch elevated high
    
    tier_label string
    
    peak_tier string
    
    Omitted for franchisee tokens.
    
    watch elevated high
    
    status string
    
    open acknowledged explained cleared
    
    status_label string
    
    opened_on string (date)
    
    last_seen_on string (date)
    
    closed_on string (date) nullable
    
    weeks_open integer
    
    Weeks the finding has been open, counting the opening week as week 1.
    
    escalation object nullable
    
    The last tier rise. Omitted for franchisee tokens.
    
    on string (date)
    
    from string
    
    to string
    
    acknowledged_by string nullable
    
    explanation object nullable
    
    reason string
    
    reason_label string
    
    note string nullable
    
    by string nullable
    
    on string (date) nullable
    
    promotion_window object nullable
    
    factors array of object
    
    The evidence behind the flag, one plain sentence per factor.
    
    key string
    
    own_history peers drift other_metric network_shift volume concentration
    
    status string
    
    hit warn ok na
    
    text string
  - network_findings array of RiskNetworkFinding
    
    Present only when a franchisor token passes include_network.
    
    id string (uuid)
    
    location object nullable
    
    Always null.
    
    metric string
    
    metric_label string
    
    status string
    
    status_label string
    
    opened_on string (date)
    
    last_seen_on string (date)
    
    closed_on string (date) nullable
    
    window_starts_on string (date) nullable
    
    breadth_pct number nullable
    
    Share of eligible stores that moved, as a percent.
    
    movers integer nullable
    
    eligible integer nullable
    
    network_rate_pct number nullable
    
    explanation object nullable
  - latest_assessment object
    
    Present only when location is passed; keyed by metric, null when the store was not assessed that night.
- message string
- message string
- message string
- errors object

curl "https://app.franchisesee.com/api/v1/risk/findings" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('FRANCHISESEE_TOKEN'))
    ->acceptJson()
    ->get('https://app.franchisesee.com/api/v1/risk/findings');

const response = await fetch('https://app.franchisesee.com/api/v1/risk/findings', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.FRANCHISESEE_TOKEN}`,
    Accept: 'application/json',
  },
});

const data = await response.json();

import os
import requests

response = requests.request(
    "GET",
    "https://app.franchisesee.com/api/v1/risk/findings",
    headers={"Authorization": f"Bearer {os.environ['FRANCHISESEE_TOKEN']}", "Accept": "application/json"},
)

data = response.json()

Response

{
    "data": {
        "latest_assessed_on": "2026-11-11",
        "count": 1,
        "total": 3,
        "summary": {
            "findings": 3,
            "stores": 2,
            "by_metric": {
                "field": {
                    "label": "Discount rate",
                    "findings": 2,
                    "stores": 2,
                    "by_tier": {
                        "field": 1
                    }
                }
            },
            "by_tier": {
                "field": 1
            },
            "stores_on_both_metrics": {
                "count": 1,
                "stores": [
                    "string"
                ]
            }
        },
        "findings": [
            {
                "id": "0f7d3b9e-5a1c-4e8f-b2d6-7c4a9e1f3b85",
                "location": {
                    "uuid": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
                    "name": "Downtown Austin",
                    "district": "Central Texas",
                    "category": "Inline"
                },
                "metric": "discount_rate",
                "metric_label": "Discount rate",
                "kind": "spike",
                "kind_label": "Spike",
                "tier": "elevated",
                "tier_label": "Elevated",
                "peak_tier": "elevated",
                "status": "explained",
                "status_label": "Explained",
                "opened_on": "2026-10-27",
                "last_seen_on": "2026-11-10",
                "closed_on": null,
                "weeks_open": 3,
                "escalation": {
                    "on": "2026-11-03",
                    "from": "watch",
                    "to": "elevated"
                },
                "acknowledged_by": null,
                "explanation": {
                    "reason": "approved_promotion",
                    "reason_label": "Approved promotion",
                    "note": "BOGO bowls weekend run by the local marketing co-op.",
                    "by": "Jordan Rivera",
                    "on": "2026-11-04",
                    "promotion_window": {
                        "name": "BOGO Bowls Weekend",
                        "starts_on": "2026-11-07",
                        "ends_on": "2026-11-09"
                    }
                },
                "factors": [
                    {
                        "key": "own_history",
                        "status": "hit",
                        "text": "Discount rate was 6.8% last week, against a usual 2.1% for this store."
                    }
                ]
            }
        ],
        "network_findings": [
            {
                "id": "2c8e4a6f-9b1d-4f3a-8e5c-1d7b3f9a5e26",
                "location": {},
                "metric": "zero_net_check_rate",
                "metric_label": "$0-check rate",
                "status": "open",
                "status_label": "Open",
                "opened_on": "2026-10-20",
                "last_seen_on": "2026-11-10",
                "closed_on": null,
                "window_starts_on": "2026-10-13",
                "breadth_pct": 41.7,
                "movers": 20,
                "eligible": 48,
                "network_rate_pct": 1.9,
                "explanation": {}
            }
        ],
        "latest_assessment": {
            "field": {
                "assessed_on": "2026-11-10",
                "rate_pct": 6.8,
                "usual_rate_pct": 2.1,
                "comparable_stores_rate_pct": 2.4,
                "comparable_store_count": 12,
                "checks": 1834,
                "flagged": true,
                "tier_label": "Elevated",
                "suppression": null,
                "suppression_label": null
            }
        }
    }
}

{
    "message": "Unauthenticated."
}

{
    "message": "This API token does not have the 'create' ability."
}

{
    "message": "The selected metric is invalid.",
    "errors": {
        "metric": [
            "The selected metric is invalid."
        ]
    }
}