> ## Documentation Index
> Fetch the complete documentation index at: https://trysalty.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Customer Success

> How an AI customer-success agent uses Salty to track accounts, log touchpoints, score health, and flag churn risk.

> **What is this?** A concrete recipe for wiring an AI customer-success agent against Salty's CRM. The agent maintains an account health score, logs every touchpoint, surfaces at-risk accounts, and drives QBR prep — all over MCP or REST.

## The scenario

You sell SaaS to 50–500 customers. You can't afford a CSM headcount per account. An LLM agent watches product usage signals, conversation transcripts, and ticket data; logs touchpoints; and when health drops, alerts you with the receipt of *why*.

Salty is the system of record. Native objects map cleanly to the CS workflow.

## Data model

| Salty object                         | Your concept                                                   |
| ------------------------------------ | -------------------------------------------------------------- |
| `company`                            | Customer account                                               |
| `person` (with `primary_company_id`) | Stakeholder at that account (champion, exec sponsor, end user) |
| `deal`                               | Renewal opportunity (one per account per renewal cycle)        |
| `activity`                           | Touchpoint — call, QBR, email, in-product nudge                |
| `note`                               | Free-form context (call notes, exec change, competitive intel) |
| `task`                               | Follow-up items (REST/CLI only — no MCP write tool in v1)      |
| `custom_attributes` on company       | `health_score`, `arr_cents`, `tier`, `last_qbr_at`             |

## Set up the schema

Extend the `company` object once at start-of-life:

```bash theme={null}
curl -X POST $SALTY_API/schema/company/attributes \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -d '{"attribute_key":"health_score","display_name":"Health Score",
       "data_type":"number"}'

curl -X POST $SALTY_API/schema/company/attributes \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -d '{"attribute_key":"tier","display_name":"Tier","data_type":"enum",
       "enum_values":["starter","growth","enterprise"]}'

curl -X POST $SALTY_API/schema/company/attributes \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -d '{"attribute_key":"arr_cents","display_name":"ARR (cents)","data_type":"number"}'
```

## What the agent does on a typical week

| Task                              | Tool calls                                                                          | Why                                 |
| --------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
| Pull the at-risk list             | `search_companies` with filter `custom_attributes.health_score < 60`                | Daily standup feed                  |
| Update health after weekly review | `update_company` setting `custom_attributes.health_score`                           | Recalculated from usage + sentiment |
| Log a CSM call                    | `log_activity` parent: company, type: `csm_call`, payload includes notes + duration | Audit trail                         |
| Add a context note from Slack     | `add_note` parent: company                                                          | Surface non-meeting signal          |
| Move renewal deal forward         | `update_deal` stage transition                                                      | Track \$\$\$ at risk                |

## Driving it from Claude Desktop

Conversational prompt:

> "Pull every company with health score below 70 and tell me who their primary contact is and when we last logged a touchpoint."

Claude will:

1. `search_companies` with `{filter: {custom_attributes: {health_score: {lt: 70}}}}` (the filter syntax)
2. For each company, `search_people` with `{filter: {primary_company_id: {equals: <id>}}}`
3. Reads each company's `last_touchpoint_at` custom attribute (returned inline in step 1, kept current by your activity logging) to show recency
4. Surface a ranked table you can act on

The whole "QBR prep" workflow is one prompt instead of 40 minutes of dashboard clicks.

## React to churn signal via webhooks

When your usage-monitoring system pushes a low-engagement event, your agent can update Salty and Salty fires a webhook to your alert channel:

```bash theme={null}
curl -X POST $SALTY_API/webhook-endpoints \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  -d '{
    "url": "https://hooks.slack.com/...",
    "subscribed_events": ["company.updated"]
  }'
```

Then your Slack receiver checks `data.custom_attributes.health_score` and pages you if it dropped below threshold. Salty does the persistence + signing + retry; you just react.

## Reporting

Get a CSV-ready dump of every company with health, ARR, and last activity:

```bash theme={null}
curl -G $SALTY_API/companies \
  -H "Authorization: Bearer $SALTY_API_KEY" \
  --data-urlencode "limit=100" > companies.json
```

The agent can run this nightly, transform to CSV, and post to your weekly dashboard.

## Volume guidance

A 100-account CS practice with weekly check-ins makes \~10,000 API calls/month (\~25 calls per account per week). The **Solo (`$20/mo`, 100k calls)** plan has 10× headroom. **Pro (`$99/mo`, 1M calls)** if you have hundreds of accounts.

## Related

* [Schema engine](/docs/concepts/schema-engine) — custom\_attributes with enum/reference/json types
* [Webhooks](/docs/webhooks/introduction) — react to state changes in real time
* [Concepts → Authentication](/docs/concepts/authentication) — sk\_live\_ vs OAuth for human-and-agent flows
* [Concepts → Rate limits](/docs/concepts/rate-limits) — per-plan ceilings + burst