When a task asks you to produce a retention operations artifact using the ApexCloud Retention Operations API, follow the process below. Every step is deterministic and grounded in the API data shapes documented here.
1. Connect and Verify
The API base URL is provided in the task prompt as <TASK_ENV_BASE_URL>.
Replace that token with the actual URL before making any call. Start with
GET /api/health to confirm the service is reachable and to see current row
counts.
All responses are JSON unless the endpoint path includes .csv. The API has no
authentication.
2. Endpoint Reference
Account Profile
GET /api/accounts — list all accounts.GET /api/accounts/{account_id} — single account.
Each account object has:
{
"account_id": "acct_...",
"display_name": "...",
"legal_name": "... LLC",
"account_aliases": ["...", "..."],
"region": "North America",
"segment": "Strategic|Enterprise|Mid-Market|SMB",
"lifecycle_status": "active|renewal_risk|paused|implementation",
"product_plan": "Strategic|Enterprise|Scale|Starter",
"renewal_date": "YYYY-MM-DD",
"contract_tenure_months": 12,
"billing_arr_current": 0.0,
"crm_arr": 0.0,
"csm_owner": "..."
}
ARR source rule: current_arr in risk/board artifacts MUST come from the
billing snapshot for the assessment as-of date (GET /api/billing/snapshots),
filtered by account_id and as_of. Never use billing_arr_current or
crm_arr from the account profile for current_arr. The policy code for this
choice is REV-4.
Monthly Metrics
GET /api/accounts/{account_id}/metrics?start=YYYY-MM&end=YYYY-MM
Returns an array of per-month records:
{
"account_id": "...",
"month": "YYYY-MM",
"quarter": "YYYY-QN",
"recognized_revenue": 0.00,
"support_ticket_count": 0,
"sla_compliance": 0.0,
"nps_score": 0,
"product_usage": 0.0,
"active_seats": 0,
"survey_status": "completed|missing"
}
nps_score is null when survey_status is "missing". The metric
recognized_revenue is labeled as source crm_closed_won in QBR artifacts
(not billing_snapshot).
Support Tickets
GET /api/accounts/{account_id}/tickets?start=YYYY-MM-DD&end=YYYY-MM-DD
Every ticket has:
{
"ticket_id": "TCK-...",
"created_date": "YYYY-MM-DD",
"severity": "P1|P2|P3|P4",
"status": "open|closed|cancelled",
"product_area": "billing|integrations|analytics|workflow|identity|mobile",
"is_duplicate": false,
"is_spam": false,
"first_response_sla_met": true,
"resolution_sla_met": true
}
Cleaning rule: a ticket is "clean" when ALL of these hold:
is_spamisfalseis_duplicateisfalsestatusis not"cancelled"
The clean ticket count for a period is the total count of tickets passing
the cleaning rule. The policy code for this convention is SUP-8.
SLA compliance from clean tickets: compute (clean tickets with both first_response_sla_met AND resolution_sla_met equal to true) / (clean ticket count), expressed as a percentage to 1 decimal place. When there are zero clean
tickets for a month, SLA compliance is 100.0.
Ticket trend (for QBR artifacts) is determined by comparing clean ticket
counts month-over-month: improving when counts consistently decrease or stay
flat, worsening when they increase, flat when no clear direction. The final
label must match the data.
NPS Responses
GET /api/accounts/{account_id}/nps?start=YYYY-MM-DD&end=YYYY-MM-DD
Only include responses where retracted is false. The latest NPS is the
score from the most recent non-retracted response within the period. When the
NPS endpoint returns no valid response for the period, fall back to the most
recent non-null nps_score from the monthly metrics endpoint.
Billing Snapshots
GET /api/billing/snapshots
Quarterly snapshots. Filter by account_id and as_of to get the billing ARR
for the assessment date. The billing_arr field is the authoritative
current_arr for risk and board artifacts.
A/R Aging
GET /api/finance/ar-aging
Each record has customer_name, as_of, quarter, region, current,
1_30, 31_60, 61_90, and 90_plus.
Overdue balance = 61_90 + 90_plus. Do NOT include 1_30 or 31_60.
The current bucket is not overdue.
Opportunities (CRM Pipeline)
GET /api/opportunities
Filter by account_id, close_date range, state ("open", "won",
"lost"), and region as needed. Summarize counts, revenue, win rate, and top
product line.
HR Summary
GET /api/hr/summary
Filter by quarter and sum across region when the task asks for all-region
context. Relevant fields: headcount, unpaid_claims_amount.
Event Performance
GET /api/events/performance
Filter by event_id and quarter. Relevant fields: event_orders,
event_revenue.
Churn Exports (CSV)
GET /exports/churn/train.csv — 180 rows, includes Churn label.GET /exports/churn/validation.csv — 60 rows, includes Churn label.GET /exports/churn/candidates.csv — 44 rows, no Churn label.GET /exports/account_metric_extract.csv — 528-row flat extract.
3. Controlled Vocabularies
Every enum value used in output artifacts must come from these exact lists. Never invent new values.
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
Review Owners
solutions_engineering | customer_success | finance_ops
Agenda Topics
partnership_overview | q2_metrics | performance_highlights | q3_initiatives | technical_recovery | commercial_expansion
Ticket Trends
improving | worsening | flat
Accuracy Bands
below_70 | 70_to_79 | 80_to_89 | 90_plus
Tenure Risk Direction
negative | positive | not_assessed
Link Status
linked | unlinked
Outreach Actions (Churn)
renewal_save | technical_recovery | collections_followup | nurture_monitor
4. Policy Codes
When a task answer template includes policy_codes, use these exact values for
the named slots. Each code is associated with a specific methodology choice.
Risk Queue (train_001 pattern)
| Slot | Code | Meaning |
|---|---|---|
risk_model_code |
RS-6 |
Risk scoring uses six-factor weighted model |
arr_source_code |
REV-4 |
ARR sourced from billing snapshots |
support_hygiene_code |
SUP-8 |
Tickets cleaned by removing spam/duplicates/cancelled |
action_priority_code |
ACT-5 |
Five-tier action priority |
QBR Packet (train_002 pattern)
No policy_codes block in the template for this task type.
Receivables Review (train_003 pattern)
| Slot | Code | Meaning |
|---|---|---|
receivable_trigger_code |
RCP-7 |
Receivables triggered from 61+ day buckets |
crm_match_code |
CM-5 |
CRM matching on legal name plus aliases |
pipeline_window_code |
PW-6 |
Pipeline window includes all close dates in quarter |
followup_scope_code |
FS-4 |
Follow-up scope covers all overdue clients |
Churn Model (train_004 pattern)
| Slot | Code | Meaning |
|---|---|---|
model_protocol_code |
MOD-7 |
Logistic regression with 19 features |
probability_scale_code |
PRB-4 |
Probabilities rounded to 3 decimals |
deployment_rule_code |
DEP-5 |
Top-5 deployment ranking |
outreach_mapping_code |
OUT-2 |
overdue→collections, low-tenure→renewal, else→nurture |
Retention Board (train_005 pattern)
| Slot | Code | Meaning |
|---|---|---|
risk_model_code |
RS-6 |
Six-factor weighted risk model |
arr_source_code |
REV-4 |
ARR from billing snapshots |
support_hygiene_code |
SUP-8 |
Ticket cleaning per SUP-8 |
action_priority_code |
ACT-5 |
Five-tier action priority |
board_sort_code |
BORD-4 |
Board sorted by risk severity then ARR |
exposure_formula_code |
EXP-6 |
Net exposure = ARR at risk minus expansion pipeline |
calendar_policy_code |
CAL-5 |
Five-action calendar with staggered dates |
5. Task-Type Recipes
5a. Renewal Risk Queue
- For each
account_idin the task list, call the account profile, then metrics (for the analysis period), tickets (full period), NPS (full period), billing snapshots (filtered to the as-of date), and AR aging (filtered to the as-of date and matching customer_name to account legal_name). - Compute for each account:
current_arr: billing snapshotbilling_arrat the as-of date.latest_nps: most recent non-retracted NPS score in the period.clean_ticket_count: total tickets minus spam, duplicates, cancelled.overdue_balance: AR aging61_90+90_plusfrom the matching AR record.- Risk factors present: check renewal proximity (within 90 days of assessment
date →
renewal_window), overdue > 0 →overdue_receivable, NPS below 40 or declining →nps_drop, SLA below 90% at end of period or declining over the period →sla_degradation, product usage declining →usage_decline, tenure ≤ 18 months →low_tenure_high_churn, open expansion pipeline →expansion_offset, zero overdue and no billing issues →clean_billings.
- Assign a risk score on a 0-100 integer scale using these weights:
renewal_window: +30overdue_receivable: +25nps_drop: +20sla_degradation: +15usage_decline: +10low_tenure_high_churn: +10expansion_offset: −10 (mitigating)clean_billings: −10 (mitigating) Clamp to [0, 100]. Break ties by highercurrent_arrfirst.
- Map risk score to risk level: ≥70 →
critical, 50-69 →high, 20-49 →medium, <20 →low. - Assign
primary_action: if overdue > 0 →collections_followup; else if (sla_degradationorusage_decline) and no overdue →technical_recovery; else ifrenewal_window→renewal_save; else ifnps_drop→executive_qbr; else ifexpansion_offset→nurture_monitor; elseno_action. - Collect
reason_codesfor each risk factor present. Removeexpansion_offsetandclean_billingsfrom reason codes when they are the sole factor and the risk level islow(unless they are the only factors, in which case keep the strongest). - Sort by risk score descending, then
current_arrdescending. Return top 5. - Portfolio summary:
accounts_reviewed(total list length),critical_or_high_count(critical + high),arr_at_risk(sum of current_arr for critical + high),collections_count(number with primary_action=collections_followup),technical_recovery_count(number with primary_action=technical_recovery). - Model checks:
uses_billing_arr_source=true,tenure_risk_direction=negative(longer tenure lowers risk).
5b. QBR Metrics Packet
- Call account profile, then metrics for the three months in the quarter.
- For each month, call tickets and compute clean SLA: filter to clean tickets
only (excluding spam, duplicates, cancelled), then compute the percentage
where both
first_response_sla_metandresolution_sla_metaretrue. Use the rawsupport_ticket_countfrom the metrics endpoint for thesupport_ticketscount shown in the output (not the clean count). revenue=recognized_revenuefrom the metrics endpoint.nps_score= the most recent non-null nps_score for that month from the metrics endpoint (not the NPS endpoint, for QBR monthly breakdown).- Highlights: compute
average_revenueacross 3 months,peak_revenue_monthandpeak_revenue,max_sla_monthandmax_sla_pct(using clean SLA),peak_nps_monthandpeak_nps_score, andticket_trend. - Metric sources:
revenue→crm_closed_won,support_tickets→support_export,sla_compliance→sla_report,nps→nps_survey. - Review plan:
review_owneriscustomer_successunless the task explicitly names another owner.needs_technical_signoffistruewhen SLA compliance dropped below 90% in any month; otherwisefalse. - Agenda topics: choose exactly four, ordered. Start with
partnership_overview, thenq2_metrics, then the most relevant two fromperformance_highlights,technical_recovery,commercial_expansion,q3_initiativesbased on the account's data signals.
5c. Receivables & Pipeline Operations Review
- Call
/api/finance/ar-agingand filter to the as-of date. - For each AR record, compute
overdue_balance=61_90+90_plus. Only include records withoverdue_balance > 0. - Call
/api/accountsto get all CRM accounts. Match each ARcustomer_nameagainst accountlegal_name(exact) andaccount_aliases(exact match on any alias string). Setlink_statusto"linked"andaccount_idto the matchedaccount_idwhen found; otherwise"unlinked"withaccount_id: null. - Sort
overdue_followupsbycustomer_nameascending. Setdue_dateto the follow-up date from the task prompt.primary_actionis alwayscollections_followupfor receivables items. - Financial summary:
overdue_client_count(distinct AR customers with overdue),overdue_total(sum of all overdue_balance),linked_followup_count(number with link_status=linked),unlinked_followup_count(number with link_status=unlinked). - Pipeline summary from
/api/opportunities: filter by quarter's date range onclose_date. Countwon,lost,openbystate. Computewin_rate_pct=won_count / (won_count + lost_count) * 100to 1 decimal.top_open_product_lineis the product line with the highest totalamountamong open opportunities. - Ops context: call
/api/hr/summaryfor the quarter, sum across all regions (or the specified region) forheadcountandunpaid_claims_amount. Call/api/events/performancefor the specified event and quarter, useevent_ordersandevent_revenue.
5d. Churn Model Validation & Outreach Ranking
- Load
/exports/churn/train.csvand/exports/churn/validation.csv. Parse with a CSV reader. The label column isChurn(values"Yes"/"No"). The feature columns are everything betweencustomer_idandChurn, inclusive ofMonthlyChargesthroughActiveSeatRatiobut excludingcustomer_idandChurn. - Encode categorical features (one-hot or label encoding). Fit a logistic regression classifier on the training data. Predict on the validation set. Compute accuracy to 1 decimal place. Map to an accuracy band.
- Extract the tenure coefficient: if negative,
tenure_coefficient_directionis"negative"; if positive,"positive"; if near zero,"zero". - Load
/exports/churn/candidates.csv. Filter to only the task-specified account IDs. Predict churn probabilities with the trained model. Sort by probability descending, take top 5. - For each candidate, assign
outreach_actionandreason_code:- If the candidate's
InvoicePastDueis"Yes"→collections_followup,overdue_receivable - Else if
tenure≤ 18 →renewal_save,low_tenure_high_churn - Else →
nurture_monitor,clean_billings
- If the candidate's
- Cohort checks:
past_due_shortlist_count(number of top 5 with InvoicePastDue=Yes),low_tenure_shortlist_count(number of top 5 with tenure ≤ 18),average_probability_top5(mean of top 5 probabilities, rounded to 3 decimals). - Probabilities rounded to 3 decimals.
5e. High-Touch Retention Action Board
- For each account in the task list, call the account profile, metrics (for the analysis period), tickets (full period), NPS (full period), billing snapshots (as-of date), and AR aging (as-of date).
- Call
/api/opportunitiesand filter for the account's open expansion opportunities whoseclose_datefalls in the analysis period. Sum theiramountasexpansion_pipeline. - Compute risk factors and risk score per the risk queue recipe (5a). Compute
current_arrfrom billing snapshots. Computeoverdue_balancefrom AR aging. - Assign
primary_actionandnext_touch_due_date:collections_followup→ next touch = collections_followup date from prompttechnical_recovery→ next touch = technical_recovery date from promptrenewal_save→ next touch = renewal_save date from promptexecutive_qbr→ next touch = executive_qbr date from promptnurture_monitor→ next touch = nurture_monitor date from promptno_action→next_touch_due_dateisnull
- Sort the action board by risk score descending, then
current_arrdescending. Include ALL accounts in the list (not just top-N). Number ranks sequentially. - Segment summary:
strategic_accounts: count of accounts withsegment="Strategic"enterprise_accounts: count withsegment="Enterprise"arr_at_risk: sum ofcurrent_arrfor all accounts whererisk_leveliscriticalorhighopen_expansion_pipeline: sum ofexpansion_pipelineacross all accountsnet_revenue_exposure:arr_at_risk-open_expansion_pipeline
- Follow-up calendar: use the exact dates from the task prompt.
6. Precision and Formatting Rules
- Currency values (revenue, ARR, balances, amounts): always 2 decimal places.
- Percentages (SLA, win rate, accuracy): always 1 decimal place.
- Counts (tickets, accounts, headcount): integers.
- Risk scores: integers 0-100.
- Churn probabilities: 3 decimal places.
- Dates:
YYYY-MM-DDstrings. - Months:
YYYY-MMstrings.
7. Output Discipline
- Return only valid JSON. No markdown fences, no explanatory text, no trailing commas.
- Match the exact JSON shape from the task's
answer_template.json. Do not add, remove, or rename keys. - Order arrays exactly as specified (e.g. risk ranking by rank ascending, overdue followups by customer_name ascending, action board by rank ascending).
- Use
null(not"null", not0, not empty string) for missing values where the template showsnull. - Every controlled enum field must contain exactly one of the allowed values listed in Section 3, never a composite or free-text value.
8. API Call Pattern
When a task lists multiple accounts, make one API call per account endpoint
family, not one mega-call. For endpoints that return all records
(/api/accounts, /api/billing/snapshots, /api/finance/ar-aging,
/api/opportunities), fetch once and filter client-side. For per-account
endpoints (/metrics, /tickets, /nps), call once per account.
Use start and end query parameters exactly as shown in the task prompt.
Date formats: YYYY-MM-DD for tickets and NPS endpoints; YYYY-MM for metrics.