ApexCloud Retention Operations Skill
This skill covers the ApexCloud Retention Operations API, a synthetic SaaS retention dataset with accounts, billing, support tickets, NPS surveys, A/R aging, opportunities pipeline, HR summaries, event performance, churn model exports, and account metric extracts.
Base URL
The task prompt provides a base URL as the <TASK_ENV_BASE_URL> placeholder. Replace it with the actual URL before making any API call. All endpoints listed below are relative to that base.
API Endpoints
See reference/api.md for the complete endpoint reference with parameter formats, response shapes, and field descriptions.
Summary of available endpoints:
| Method |
Path |
Purpose |
| GET |
/api/health |
Service health and row counts |
| GET |
/api/accounts |
All CRM accounts |
| GET |
/api/accounts/{id} |
Single account details |
| GET |
/api/accounts/{id}/metrics?start=YYYY-MM&end=YYYY-MM |
Monthly metrics per account |
| GET |
/api/accounts/{id}/tickets?start=YYYY-MM-DD&end=YYYY-MM-DD |
Support tickets per account |
| GET |
/api/accounts/{id}/nps?start=YYYY-MM-DD&end=YYYY-MM-DD |
NPS survey responses per account |
| GET |
/api/billing/snapshots |
Quarterly billing snapshots |
| GET |
/api/finance/ar-aging |
Global A/R aging by quarter |
| GET |
/api/opportunities |
All CRM opportunities |
| GET |
/api/hr/summary |
HR summaries by region and quarter |
| GET |
/api/events/performance |
Event performance by quarter |
| GET |
/exports/churn/train.csv |
Churn model training set |
| GET |
/exports/churn/validation.csv |
Churn model validation set |
| GET |
/exports/churn/candidates.csv |
Churn candidate accounts |
| GET |
/exports/account_metric_extract.csv |
Full account metric extract |
Controlled Vocabularies
Every task uses controlled enum labels. See reference/vocabularies.md for the complete set. Never invent or approximate these values. The vocabularies are organized by domain:
- Risk levels:
critical, high, medium, low
- Primary actions:
collections_followup, technical_recovery, renewal_save, executive_qbr, nurture_monitor, no_action
- Reason codes:
overdue_receivable, low_tenure_high_churn, sla_degradation, nps_drop, usage_decline, renewal_window, expansion_offset, clean_billings
- Metric sources:
crm_closed_won, support_export, sla_report, nps_survey, billing_snapshot, ar_aging, pipeline_crm, event_dashboard, hr_report
- Ticket trends:
improving, worsening, flat
- Review owners:
solutions_engineering, customer_success, finance_ops
- Agenda topics:
partnership_overview, q2_metrics, performance_highlights, q3_initiatives, technical_recovery, commercial_expansion
- Link status:
linked, unlinked
- Accuracy bands:
below_70, 70_to_79, 80_to_89, 90_plus
- Coefficient directions:
negative, positive, zero, not_assessed
- Outreach actions:
renewal_save, technical_recovery, collections_followup, nurture_monitor
- Policy codes: See vocabulary reference for all
RS-*, REV-*, SUP-*, ACT-*, RCP-*, CM-*, PW-*, FS-*, MOD-*, PRB-*, DEP-*, OUT-*, BORD-*, EXP-*, CAL-* codes.
Numeric Precision Rules
Apply these conventions to every output value:
| Value type |
Precision |
Example |
| Currency (revenue, ARR, balances, pipeline) |
2 decimal places |
1234567.89 |
| Percentages (SLA, win rate, accuracy) |
1 decimal place |
93.3 |
| Counts (tickets, accounts, headcount) |
Integer |
13 |
| Risk scores |
Integer |
100 |
| Churn probabilities |
3 decimal places |
0.102 |
| NPS scores |
Integer |
39 |
For null values: use JSON null only when the source data is truly unavailable. Zero 0 and 0.0 are distinct from null.
Data Reconciliation Rules
Account matching across APIs
The /api/accounts endpoint returns CRM accounts with account_id, legal_name, and account_aliases. Other endpoints use customer_name (A/R aging) or account_legal_name (opportunities). To reconcile:
- Match by exact
account_id where available.
- When only a
customer_name is present (A/R aging), check it against legal_name fields across all accounts.
- If no exact legal_name match, check
customer_name against account_aliases arrays.
- Mark
link_status as "linked" when a CRM account match is found, "unlinked" otherwise.
Ticket cleaning
When computing clean ticket counts:
- Exclude tickets where
is_duplicate is true.
- Exclude tickets where
is_spam is true.
- Count only the remaining tickets.
- Use the
created_date field for period filtering.
SLA compliance for individual months: the metrics endpoint provides pre-computed sla_compliance values. When computing SLA from raw tickets, count tickets where resolution_sla_met is true among clean tickets in the period, and divide by total clean tickets.
NPS handling
- The
/api/accounts/{id}/metrics endpoint includes pre-computed nps_score per month.
- The
/api/accounts/{id}/nps endpoint returns individual responses with score and retracted fields.
- Exclude retracted responses (
retracted is true) when computing NPS from raw responses.
- Use the most recent non-retracted NPS score within the analysis period as
latest_nps.
ARR sources
Two ARR figures exist per account:
crm_arr from /api/accounts/{id} -- CRM-sourced ARR.
billing_arr_current from /api/accounts/{id} -- billing-sourced ARR.
billing_arr from /api/billing/snapshots -- quarterly billing snapshot ARR.
When a task requires current_arr or billing_arr_source, use the billing snapshot matching the assessment date's quarter. The account_metric_extract.csv uses recognized_revenue from metrics, not ARR.
Overdue balance calculation
Sum the aging buckets beyond current: 1_30 + 31_60 + 61_90 + 90_plus. Filter A/R records by the specified as-of date. The current bucket represents not-yet-due amounts and is excluded from overdue totals.
Usage trend detection
Compare product_usage values month-over-month from the metrics endpoint. If adjacent months show declining usage in consecutive periods, flag usage_decline. The account_metric_extract.csv provides the same data in bulk.
Tenure risk
- Shorter
contract_tenure_months correlates with higher churn risk.
- The churn model exports confirm this:
tenure_coefficient_direction is "negative" (lower tenure = higher churn probability).
- Apply
low_tenure_high_churn as a reason code for accounts below approximately 24 months tenure when combined with other risk signals.
Task Pattern Reference
Each task type follows a predictable flow:
Renewal Risk Queue
Fetch accounts, then metrics/tickets/NPS/billing/A/R for each account_id in the scoped list. Score each account using weighted signals: renewal proximity, overdue balance, NPS trajectory, SLA degradation, usage decline, tenure, and expansion offsets. Rank by descending risk_score. Use the risk_level vocabulary for classification thresholds.
QBR Metrics Packet
Fetch a single account's metrics for the given month range. Also fetch tickets and NPS responses raw to confirm source attribution. Compute highlights (averages, peaks, trends) from the monthly data. Assign metric_sources enum values based on which endpoint supplied each metric. Select agenda topics that match the account's actual situation.
Receivables and Pipeline Operations Review
Fetch A/R aging filtered by quarter/as-of date. For each overdue customer, attempt to match to a CRM account via legal_name/aliases. Fetch opportunities for pipeline summary (won/lost/open counts and revenue, filtered by the given date range). Fetch HR and events for ops_context. Sort overdue_followups by customer_name ascending.
Churn Model Validation
Fetch all three CSV exports. Parse CSV with a proper parser (Python csv module or csv.DictReader). Compute validation statistics: row counts, feature count, accuracy, accuracy band. Rank candidate accounts by predicted_churn_probability descending. Map outreach actions based on churn probability thresholds and known risk factors. Compute cohort checks: counts of past-due and low-tenure candidates among the ranked set, average probability of top 5.
High-Touch Retention Operations Board
Fetch accounts, billing snapshots, metrics, tickets, NPS, A/R aging, and opportunities for all scoped accounts. For each account, assess: ARR (from billing snapshot), overdue balance (from A/R), NPS trajectory, SLA health, usage trend, renewal timing, and expansion pipeline. Score and rank. Assign risk_level, primary_action, next_touch_due_date from the provided follow-up calendar, and reason_codes. Compute segment_summary (strategic vs enterprise counts, total ARR at risk, open expansion pipeline, net revenue exposure = ARR at risk minus expansion pipeline).
CSV Parsing
When fetching CSV exports, use Python's csv.DictReader for reliable parsing. Parse numeric fields explicitly:
import csv, io, urllib.request
def fetch_csv(url):
with urllib.request.urlopen(url) as resp:
text = resp.read().decode('utf-8')
return list(csv.DictReader(io.StringIO(text)))
API Calling Conventions
- Use
curl with -s for silence and pipe through python3 -m json.tool for readable output when exploring.
- When scripting, use Python
urllib.request with json.loads().
- Always URL-encode query parameters (Python's
urllib.parse.urlencode).
- Date formats: metrics use
YYYY-MM (e.g., 2026-04), tickets and NPS use YYYY-MM-DD (e.g., 2026-04-01).
- The API returns JSON arrays wrapped in objects with a
count field for list endpoints. Access the data via the named key (e.g., data["accounts"], data["metrics"], data["tickets"]).
Output Format
- Return valid JSON only unless the task explicitly requests another format.
- Follow the exact JSON shape specified in the task or its payload template.
- Do not include explanatory text, markdown fences, or commentary outside the JSON structure.
- Sort ordered lists exactly as specified (by rank, by customer_name ascending, etc.).
- Include all required top-level keys; omit optional keys only when the task explicitly allows it.
1---2name: apexcloud-retention-ops-293description: Solve ApexCloud Retention Operations API tasks using the staged task environment. Covers renewal risk queues, QBR packets, receivables reviews, churn model validation, and retention action boards.4metadata:5 source: https://skillmd.com/skills/prism-shadow/apexcloud-retention-ops-296---78# ApexCloud Retention Operations Skill910This skill covers the ApexCloud Retention Operations API, a synthetic SaaS retention dataset with accounts, billing, support tickets, NPS surveys, A/R aging, opportunities pipeline, HR summaries, event performance, churn model exports, and account metric extracts.1112## Base URL1314The task prompt provides a base URL as the `<TASK_ENV_BASE_URL>` placeholder. Replace it with the actual URL before making any API call. All endpoints listed below are relative to that base.1516## API Endpoints1718See [reference/api.md](reference/api.md) for the complete endpoint reference with parameter formats, response shapes, and field descriptions.1920Summary of available endpoints:2122| Method | Path | Purpose |23|--------|------|---------|24| GET | `/api/health` | Service health and row counts |25| GET | `/api/accounts` | All CRM accounts |26| GET | `/api/accounts/{id}` | Single account details |27| GET | `/api/accounts/{id}/metrics?start=YYYY-MM&end=YYYY-MM` | Monthly metrics per account |28| GET | `/api/accounts/{id}/tickets?start=YYYY-MM-DD&end=YYYY-MM-DD` | Support tickets per account |29| GET | `/api/accounts/{id}/nps?start=YYYY-MM-DD&end=YYYY-MM-DD` | NPS survey responses per account |30| GET | `/api/billing/snapshots` | Quarterly billing snapshots |31| GET | `/api/finance/ar-aging` | Global A/R aging by quarter |32| GET | `/api/opportunities` | All CRM opportunities |33| GET | `/api/hr/summary` | HR summaries by region and quarter |34| GET | `/api/events/performance` | Event performance by quarter |35| GET | `/exports/churn/train.csv` | Churn model training set |36| GET | `/exports/churn/validation.csv` | Churn model validation set |37| GET | `/exports/churn/candidates.csv` | Churn candidate accounts |38| GET | `/exports/account_metric_extract.csv` | Full account metric extract |3940## Controlled Vocabularies4142Every task uses controlled enum labels. See [reference/vocabularies.md](reference/vocabularies.md) for the complete set. Never invent or approximate these values. The vocabularies are organized by domain:4344- **Risk levels**: `critical`, `high`, `medium`, `low`45- **Primary actions**: `collections_followup`, `technical_recovery`, `renewal_save`, `executive_qbr`, `nurture_monitor`, `no_action`46- **Reason codes**: `overdue_receivable`, `low_tenure_high_churn`, `sla_degradation`, `nps_drop`, `usage_decline`, `renewal_window`, `expansion_offset`, `clean_billings`47- **Metric sources**: `crm_closed_won`, `support_export`, `sla_report`, `nps_survey`, `billing_snapshot`, `ar_aging`, `pipeline_crm`, `event_dashboard`, `hr_report`48- **Ticket trends**: `improving`, `worsening`, `flat`49- **Review owners**: `solutions_engineering`, `customer_success`, `finance_ops`50- **Agenda topics**: `partnership_overview`, `q2_metrics`, `performance_highlights`, `q3_initiatives`, `technical_recovery`, `commercial_expansion`51- **Link status**: `linked`, `unlinked`52- **Accuracy bands**: `below_70`, `70_to_79`, `80_to_89`, `90_plus`53- **Coefficient directions**: `negative`, `positive`, `zero`, `not_assessed`54- **Outreach actions**: `renewal_save`, `technical_recovery`, `collections_followup`, `nurture_monitor`55- **Policy codes**: See vocabulary reference for all `RS-*`, `REV-*`, `SUP-*`, `ACT-*`, `RCP-*`, `CM-*`, `PW-*`, `FS-*`, `MOD-*`, `PRB-*`, `DEP-*`, `OUT-*`, `BORD-*`, `EXP-*`, `CAL-*` codes.5657## Numeric Precision Rules5859Apply these conventions to every output value:6061| Value type | Precision | Example |62|------------|-----------|---------|63| Currency (revenue, ARR, balances, pipeline) | 2 decimal places | `1234567.89` |64| Percentages (SLA, win rate, accuracy) | 1 decimal place | `93.3` |65| Counts (tickets, accounts, headcount) | Integer | `13` |66| Risk scores | Integer | `100` |67| Churn probabilities | 3 decimal places | `0.102` |68| NPS scores | Integer | `39` |6970For `null` values: use JSON `null` only when the source data is truly unavailable. Zero `0` and `0.0` are distinct from `null`.7172## Data Reconciliation Rules7374### Account matching across APIs7576The `/api/accounts` endpoint returns CRM accounts with `account_id`, `legal_name`, and `account_aliases`. Other endpoints use `customer_name` (A/R aging) or `account_legal_name` (opportunities). To reconcile:77781. Match by exact `account_id` where available.792. When only a `customer_name` is present (A/R aging), check it against `legal_name` fields across all accounts.803. If no exact legal_name match, check `customer_name` against `account_aliases` arrays.814. Mark `link_status` as `"linked"` when a CRM account match is found, `"unlinked"` otherwise.8283### Ticket cleaning8485When computing clean ticket counts:86871. Exclude tickets where `is_duplicate` is `true`.882. Exclude tickets where `is_spam` is `true`.893. Count only the remaining tickets.904. Use the `created_date` field for period filtering.9192SLA compliance for individual months: the metrics endpoint provides pre-computed `sla_compliance` values. When computing SLA from raw tickets, count tickets where `resolution_sla_met` is `true` among clean tickets in the period, and divide by total clean tickets.9394### NPS handling9596- The `/api/accounts/{id}/metrics` endpoint includes pre-computed `nps_score` per month.97- The `/api/accounts/{id}/nps` endpoint returns individual responses with `score` and `retracted` fields.98- Exclude retracted responses (`retracted` is `true`) when computing NPS from raw responses.99- Use the most recent non-retracted NPS score within the analysis period as `latest_nps`.100101### ARR sources102103Two ARR figures exist per account:104105- `crm_arr` from `/api/accounts/{id}` -- CRM-sourced ARR.106- `billing_arr_current` from `/api/accounts/{id}` -- billing-sourced ARR.107- `billing_arr` from `/api/billing/snapshots` -- quarterly billing snapshot ARR.108109When a task requires `current_arr` or `billing_arr_source`, use the billing snapshot matching the assessment date's quarter. The `account_metric_extract.csv` uses `recognized_revenue` from metrics, not ARR.110111### Overdue balance calculation112113Sum the aging buckets beyond current: `1_30 + 31_60 + 61_90 + 90_plus`. Filter A/R records by the specified as-of date. The `current` bucket represents not-yet-due amounts and is excluded from overdue totals.114115### Usage trend detection116117Compare `product_usage` values month-over-month from the metrics endpoint. If adjacent months show declining usage in consecutive periods, flag `usage_decline`. The `account_metric_extract.csv` provides the same data in bulk.118119### Tenure risk120121- Shorter `contract_tenure_months` correlates with higher churn risk.122- The churn model exports confirm this: `tenure_coefficient_direction` is `"negative"` (lower tenure = higher churn probability).123- Apply `low_tenure_high_churn` as a reason code for accounts below approximately 24 months tenure when combined with other risk signals.124125## Task Pattern Reference126127Each task type follows a predictable flow:128129### Renewal Risk Queue130131Fetch accounts, then metrics/tickets/NPS/billing/A/R for each account_id in the scoped list. Score each account using weighted signals: renewal proximity, overdue balance, NPS trajectory, SLA degradation, usage decline, tenure, and expansion offsets. Rank by descending risk_score. Use the `risk_level` vocabulary for classification thresholds.132133### QBR Metrics Packet134135Fetch a single account's metrics for the given month range. Also fetch tickets and NPS responses raw to confirm source attribution. Compute highlights (averages, peaks, trends) from the monthly data. Assign `metric_sources` enum values based on which endpoint supplied each metric. Select agenda topics that match the account's actual situation.136137### Receivables and Pipeline Operations Review138139Fetch A/R aging filtered by quarter/as-of date. For each overdue customer, attempt to match to a CRM account via legal_name/aliases. Fetch opportunities for pipeline summary (won/lost/open counts and revenue, filtered by the given date range). Fetch HR and events for ops_context. Sort overdue_followups by customer_name ascending.140141### Churn Model Validation142143Fetch all three CSV exports. Parse CSV with a proper parser (Python `csv` module or `csv.DictReader`). Compute validation statistics: row counts, feature count, accuracy, accuracy band. Rank candidate accounts by `predicted_churn_probability` descending. Map outreach actions based on churn probability thresholds and known risk factors. Compute cohort checks: counts of past-due and low-tenure candidates among the ranked set, average probability of top 5.144145### High-Touch Retention Operations Board146147Fetch accounts, billing snapshots, metrics, tickets, NPS, A/R aging, and opportunities for all scoped accounts. For each account, assess: ARR (from billing snapshot), overdue balance (from A/R), NPS trajectory, SLA health, usage trend, renewal timing, and expansion pipeline. Score and rank. Assign risk_level, primary_action, next_touch_due_date from the provided follow-up calendar, and reason_codes. Compute segment_summary (strategic vs enterprise counts, total ARR at risk, open expansion pipeline, net revenue exposure = ARR at risk minus expansion pipeline).148149## CSV Parsing150151When fetching CSV exports, use Python's `csv.DictReader` for reliable parsing. Parse numeric fields explicitly:152153```python154import csv, io, urllib.request155156def fetch_csv(url):157 with urllib.request.urlopen(url) as resp:158 text = resp.read().decode('utf-8')159 return list(csv.DictReader(io.StringIO(text)))160```161162## API Calling Conventions163164- Use `curl` with `-s` for silence and pipe through `python3 -m json.tool` for readable output when exploring.165- When scripting, use Python `urllib.request` with `json.loads()`.166- Always URL-encode query parameters (Python's `urllib.parse.urlencode`).167- Date formats: metrics use `YYYY-MM` (e.g., `2026-04`), tickets and NPS use `YYYY-MM-DD` (e.g., `2026-04-01`).168- The API returns JSON arrays wrapped in objects with a `count` field for list endpoints. Access the data via the named key (e.g., `data["accounts"]`, `data["metrics"]`, `data["tickets"]`).169170## Output Format171172- Return **valid JSON only** unless the task explicitly requests another format.173- Follow the exact JSON shape specified in the task or its payload template.174- Do not include explanatory text, markdown fences, or commentary outside the JSON structure.175- Sort ordered lists exactly as specified (by rank, by customer_name ascending, etc.).176- Include all required top-level keys; omit optional keys only when the task explicitly allows it.