API v3 is live and in beta: expect possible malfunctions and breaking changes in the coming days. If you find a bug, please report it to your Sillage contact.

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

PUT/api/v3/account-monitoring/accounts

Access modes

Use a workspace API key. The workspace is inferred from the key.

Authorization: Bearer sk_live_...

Body parameters

ParameterTypeDescription
persona_idintegerID 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_idsarray of integerIDs of the companies to change, between 1 and 1000: the id of a list member, as returned by List members. Required.
signal_bucketsarray 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

FieldTypeDescription
data.changedarray of objectAccounts that changed, with their status read back once billing ran.
data.changed[].company_idintegerID of the company.
data.changed[].statusstringmonitored, not_covered, monitored_elsewhere or not_monitored. See the statuses.
data.changed[].covered_untilstring or nullEnd of the month already paid, as an ISO 8601 timestamp. After a stop, when signals stop. null when nothing is paid.
data.already_in_statearray of integerIDs of the companies already in the requested state. They are not charged again.
data.rejectedarray of objectAccounts that cannot be changed, each with the account as you sent it, a code and a message. See the table below.
data.rejected[].inputobjectThe account as you sent it: { "company_id": 304 }.
data.rejected[].codestringWhy the account is rejected: one of the codes below. New codes may be added; ignore codes you don't know.
data.rejected[].messagestringA plain sentence saying what is wrong and, when you can fix it, how.
data.charged_creditsnumberWhat this request took from your balance, in credits, renewals already due included. 0 when a partner pays.
data.balance_after_creditsinteger or nullYour credit balance once billing ran, in whole credits rounded down. null when a partner pays.

Rejection codes

CodeMeaning
workspace_wide_list_onlyThe 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_foundThe company ID is not known to your workspace.
not_in_personaThe account is not on a customer or prospect list of this persona.
monitored_through_workspace_wide_listWhen 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

StatusMeaning
401The API key is missing or invalid.
402Your workspace has no active plan (paywall_required). Start your trial or choose a plan at https://www.getsillage.com/paywall, then retry.
422Invalid 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.
429Rate limit exceeded.
500An 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.

On this page