Reputation, Reviews, Red Flags & CSAT API

All Reputation endpoints honor your organisation’s configured Business Hours & Public Holidays clock (response_time_bh), enforce Admin Account Sync Scope, and exclude moderated reported_irrelevant and deferred_deleted reviews from pending-reply denominators.

1. Reputation Executive Summary (GET /api/v1/reports/reputation/summary)

Endpoint: GET https://profilepilotapp.com/api/v1/reports/reputation/summary Required Scope: reports:read or reputation:read Required Product Subscription: Locations & Reputation + Developer API Access

Query Parameters:

• startDate & endDate (YYYY-MM-DD, optional) — Defaults to last 30 days UTC.
• storeCode or store_code (string, optional) — Filter reviews and sentiment to a single branch.

Performance Metrics & Response Fields:

• summary.total_reviews (number) — Total reviews ingested in the date range.
• summary.average_rating (number | null) — Mean star rating (1.00–5.00) across rated reviews.
• summary.star_distribution (object) — Exact review counts keyed by "1", "2", "3", "4", "5".
• summary.replied_count (number) & summary.needs_response_count (number) — Actionable reply counts (reported_irrelevant and deferred_deleted reviews do not count as needing a response).
• summary.response_rate_pct (number) — replied_count / (replied_count + needs_response_count) × 100.
• summary.avg_response_business_minutes (number | null) & summary.avg_response_time_bh (string) — Mean response duration measured strictly inside your configured business hours (excluding weekends, closed hours, and public holidays).
• red_flags — { total, open, resolved, by_severity: { red, orange, yellow } } scoped to your active account sync filter.
• sentiment.pillars[] — Transactional sentiment topic groups (including Service, Quality, Pricing, Hygiene, Stock, and Delivery) with positive/neutral/negative breakdowns.
• sentiment.keywords[] — Top recurring positive and negative terms extracted from review text.
• sentiment.optimization_impact & sentiment.recommendations[] — Actionable CX improvement priorities.

2. Paginated Customer Reviews (GET /api/v1/reputation/reviews)

Endpoint: GET https://profilepilotapp.com/api/v1/reputation/reviews Required Scope: reputation:read or reports:read Required Product Subscription: Locations & Reputation + Developer API Access

Query Parameters:

• startDate & endDate (YYYY-MM-DD, optional — defaults to last 30 days UTC)
• storeCode or store_code (string, optional)
• platform ("google" | "meta" | "instagram", optional)
• rating (1..5 or "ONE".."FIVE", optional)
• needsResponse or needs_response ("true" | "false", optional)
• limit (1–500, default 100) & offset (default 0)

Performance Metrics & Response Fields (`reviews[]`):

• id (string), platform (string), store_code (string | null), location_id (string | null), location_name (string humanized store display name).
• star_rating (1–5 number | null) & star_rating_enum ("ONE".."FIVE" | null).
• reviewer_display_name (string | null), comment (string | null), created_at (string ISO-8601).
• moderation_status (string | null), manual_topic_tags (string[]), needs_response (boolean).
• reply ({ comment, created_at, updated_at } | null).
• response_time_bh ({ business_minutes: number | null, formatted: string | null }, e.g. { "business_minutes": 38, "formatted": "38m" }).

3. Red Flag Alerts (GET /api/v1/reputation/red-flags)

Endpoint: GET https://profilepilotapp.com/api/v1/reputation/red-flags Required Scope: reputation:read or reports:read Required Product Subscription: Locations & Reputation + Developer API Access

Query Parameters:

• startDate & endDate (YYYY-MM-DD, optional — defaults to last 30 days UTC)
• status ("open" | "resolved" | "all", optional, default "all")
• severity ("red" | "orange" | "yellow", optional)
• limit (1–500, default 100) & offset (default 0)

Performance Metrics & Response Fields (`red_flags[]`):

• id, review_id, location_id, location_name (humanized store name), platform ("google" | "facebook" | "instagram").
• alert_level ("red" | "orange" | "yellow"), category (string | null), matched_keywords (string[]).
• review_rating (string | null), review_text (string | null).
• is_resolved (boolean), resolved_at (string | null), resolution_notes (string | null), created_at (string).

4. Customer Satisfaction / Review Perks Triage Queue (GET /api/v1/reputation/csat)

Endpoint: GET https://profilepilotapp.com/api/v1/reputation/csat Required Scope: reputation:read or reports:read Required Product Subscription: Locations & Reputation + Developer API Access

Query Parameters:

• status ("pending_outreach" | "under_investigation" | "outreach_sent" | "resolved" | "closed", optional)
• storeCode or store_code (string, optional)
• limit (1–500, default 100) & offset (default 0)

Performance Metrics & Response Fields:

• sla — Configured CSAT outreach targets: { firstContactSlaHours, resolutionSlaHours }.
• status_counts — Live queue totals across { pending_outreach, under_investigation, outreach_sent, resolved, closed }.
• cases[] — Individual customer opt-in cases (id, email, mobile_number, order_number, source, created_at, review_id, case_status, case_notes, status_updated_at, linked_red_flag_id, and nested review: { reviewer_name, star_rating, location_name, comment }).

5. Troubleshooting & Common Scenarios

• Why is `response_time_bh.business_minutes` lower than wall-clock time? ProfilePilot measures review response SLA strictly during your organisation’s configured business hours (and pauses the clock overnight, on weekends, and on regional public holidays).
• Why is `needs_response: false` on an unreplied review? If a review’s moderation_status is reported_irrelevant or deferred_deleted, it is excluded from needs_response and from response_rate_pct denominators so spam does not penalize store managers.
• Account Sync Scope filtering: Red Flag alerts and reviews automatically respect the organisation’s Admin Account Sync Scope (sync_included_accounts_*), matching Mission Control and the portal.