Monitor or stop accounts
Start or stop monitoring a selection of accounts in one persona.
Monitors or stops a selection of accounts in one persona, and bills it right away: send signal_buckets: ["essential"] to monitor them, null to stop. Monitoring costs price_per_account_credits credits per account and per persona for a month: read the price in Get monitoring summary.
Accounts are monitored through the lists attached to that persona: an account that only sits on lists attached to no persona is refused. Monitor such a list as a whole with Update a list instead: it is then monitored, and charged, in every active persona. When a list is attached to several personas, monitoring an account on it monitors, and charges, it in each of them, and stopping it stops it in each of them. Stopping keeps the month already paid until its end and never refunds it.
The request is never refused for lack of credits: an account whose month cannot be paid comes back with the status not_covered in changed. The response tells what the request took from your balance in charged_credits. A request where every account is rejected still answers 200. Every change is recorded in the membership log of the lists involved.
To monitor a whole list, including the accounts added to it later, set its signal_buckets with PATCH /api/v3/lists/{kind}/{list_id}. See the account monitoring overview.
Route
Access modes
Use a workspace API key. The workspace is inferred from the key.
Authorization: Bearer sk_live_...Body parameters
| Parameter | Type | Description |
|---|---|---|
| persona_id | integer | ID of the persona. Optional when your workspace has exactly one active persona; required when it has several (the request is refused with a 422 otherwise). |
| company_ids | array of integer | IDs of the companies to change, between 1 and 1000: the id of a list member, as returned by List members. Required. |
| signal_buckets | array of string or null | ["essential"] to monitor the accounts, null to stop monitoring them. Required. |
Example request
curl -X PUT "https://api.getsillage.com/api/v3/account-monitoring/accounts" \
-H "Authorization: Bearer $SILLAGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"persona_id": 12,
"company_ids": [
301,
302,
303
],
"signal_buckets": [
"essential"
]
}'Success response
Status: 200 OK
{
"data": {
"changed": [
{
"company_id": 301,
"status": "monitored",
"covered_until": "2026-11-08T09:30:00.000Z"
},
{
"company_id": 302,
"status": "not_covered",
"covered_until": null
}
],
"already_in_state": [303],
"rejected": [],
"charged_credits": 50,
"balance_after_credits": 20
}
}An account that cannot be changed comes back in rejected instead of changed:
{
"data": {
"changed": [],
"already_in_state": [],
"rejected": [
{
"input": { "company_id": 304 },
"code": "not_in_persona",
"message": "This account is not on a customer or prospect list of this persona."
}
],
"charged_credits": 0,
"balance_after_credits": 20
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.changed | array of object | Accounts that changed, with their status read back once billing ran. |
| data.changed[].company_id | integer | ID of the company. |
| data.changed[].status | string | monitored, not_covered, monitored_elsewhere or not_monitored. See the statuses. |
| data.changed[].covered_until | string or null | End of the month already paid, as an ISO 8601 timestamp. After a stop, when signals stop. null when nothing is paid. |
| data.already_in_state | array of integer | IDs of the companies already in the requested state. They are not charged again. |
| data.rejected | array of object | Accounts that cannot be changed, each with the account as you sent it, a code and a message. See the table below. |
| data.rejected[].input | object | The account as you sent it: { "company_id": 304 }. |
| data.rejected[].code | string | Why the account is rejected: one of the codes below. New codes may be added; ignore codes you don't know. |
| data.rejected[].message | string | A plain sentence saying what is wrong and, when you can fix it, how. |
| data.charged_credits | number | What this request took from your balance, in credits, renewals already due included. 0 when a partner pays. |
| data.balance_after_credits | integer or null | Your credit balance once billing ran, in whole credits rounded down. null when a partner pays. |
Rejection codes
| Code | Meaning |
|---|---|
| workspace_wide_list_only | The account is only on lists attached to no persona. Add it to a list attached to this persona first. Only in a workspace with several personas. |
| not_found | The company ID is not known to your workspace. |
| not_in_persona | The account is not on a customer or prospect list of this persona. |
| monitored_through_workspace_wide_list | When stopping: the account is monitored through a list attached to no persona. Stop that list instead. Only in a workspace with several personas. |
New codes may be added; ignore codes you don't know.
Errors
| Status | Meaning |
|---|---|
| 401 | The API key is missing or invalid. |
| 402 | Your workspace has no active plan (paywall_required). Start your trial or choose a plan at https://www.getsillage.com/paywall, then retry. |
| 422 | Invalid body (company_ids empty or above 1000, signal_buckets missing), an unknown persona_id, the workspace has no persona (Persona incomplete: create one with POST /v3/personas), or persona_id missing while your workspace has several personas. |
| 429 | Rate limit exceeded. |
| 500 | An unexpected server error occurred. |
Error responses use RFC 9457 problem documents with Content-Type: application/problem+json. type is always about:blank; code tells one problem from another, detail says what went wrong this time, and errors names the field at fault.