Monitor or stop accounts

Monitors or stops a selection of accounts in one persona, and invoices it: send signal_buckets: ["essential"] to monitor them, null to stop. Each account is invoiced to you per persona and per month, at your partner price.

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 invoiced, in every active persona. When a list is attached to several personas, monitoring an account on it monitors it in each of them, and stopping it stops it in each of them. Stopping keeps the month already invoiced until its end and never credits it back.

Monitoring is invoiced, not taken from a balance, so the request is never refused for lack of credits and no account comes back not_covered. charged_credits is always 0 and balance_after_credits always null. A request where every account is rejected still answers 200.

To monitor a whole list, including the accounts added to it later, set its signal_buckets with PATCH /api/v3/partner/workspaces/{partner_workspace_id}/lists/{kind}/{list_id}. See the account monitoring overview.

Same request as the client API, resolved for the client named by partner_workspace_id instead of an API key.

Route

PUT/api/v3/partner/workspaces/{partner_workspace_id}/account-monitoring/accounts

Path parameters

Parameter	Type	Description
partner_workspace_id	string	Your own ID for the client workspace, as you chose it at creation. URL-encode it in the path.

Body parameters

Parameter	Type	Description
persona_id	integer	ID of the persona. Optional when the client's 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/partner/workspaces/ws_123/account-monitoring/accounts" \
  -H "Authorization: Bearer $SILLAGE_MASTER_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": "monitored",
        "covered_until": "2026-11-08T09:30:00.000Z"
      }
    ],
    "already_in_state": [303],
    "rejected": [],
    "charged_credits": 0,
    "balance_after_credits": null
  }
}

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": null
  }
}

Response fields

Field	Type	Description
data.changed	array of object	Accounts that changed, with their status read back once the change ran.
data.changed[].company_id	integer	ID of the company.
data.changed[].status	string	`monitored`, `monitored_elsewhere` or `not_monitored`. See the statuses.
data.changed[].covered_until	string or null	End of the month already invoiced, as an ISO 8601 timestamp. After a stop, when signals stop. `null` when no month is running.
data.already_in_state	array of integer	IDs of the companies already in the requested state. They are not invoiced 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	Always `0`: monitoring is invoiced to you, not taken from a balance.
data.balance_after_credits	integer or null	Always `null` (an integer for a client): partner workspaces have no credit balance.

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 the client's 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 master key is missing or invalid.
404	No workspace found for this `partner_workspace_id`.
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/partner/workspaces/{partner_workspace_id}/personas`), or `persona_id` missing while the client's 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.

Monitor or stop accounts

On this page