Add Accounts

Merges the provided accounts into the workspace's existing top account list. This is an asynchronous operation — the 202 confirms the accounts were accepted for ingestion. Accounts already present in the list are deduplicated silently; submitting duplicates is not an error. Poll Get ingestion status until ingestion completes, then read the enriched results with List accounts.

Credit usage

Adding accounts consumes credits from your workspace balance: mapping each account and analyzing its relevant employees' content both consume credits, per account and per analyzed profile. This processing happens asynchronously, so a workspace that runs out of credits does not receive an error here — processing simply pauses until credits are added.

Limited trial quota

Workspaces on a limited trial plan can only add a capped number of accounts over the lifetime of the workspace. The quota only counts accounts that are actually new: submitting accounts already in your list does not consume it, and removing accounts never frees quota back up. A request that would push you over your remaining quota is rejected in full — none of the submitted accounts are added — so retry with a smaller, curated list. See Errors below.

Minimum setup required

Before adding accounts, your workspace must have a persona with a location that resolves to at least one country. Without that, there is no country to run account mapping against, so the accounts you submit would never get mapped.

If this requirement is not met, the request is refused with 422 and a message telling you to update your persona, for example:

"Persona has no location that resolves to a country. Update it with sillage_v2_upsert_persona before adding top accounts."

The response also includes a type field identifying the rejection, so your code can check it instead of parsing the message: https://docs.getsillage.com/errors/persona-incomplete.

{
  "type": "https://docs.getsillage.com/errors/persona-incomplete",
  "title": "Persona incomplete",
  "status": 422,
  "detail": "Persona has no location that resolves to a country. Update it with sillage_v2_upsert_persona before adding top accounts.",
  "instance": "/api/v2/top-account-list/accounts"
}

Add accounts

POST/api/v2/top-account-list/accounts

Request body

Field	Type	Required	Description
accounts	array	Yes	Accounts to add. Minimum 1 entry, maximum 10,000 entries. Each entry must include at least one of `linkedin_url` or `domain`.

Each account item:

Field	Type	Required	Description
linkedin_url	string	One of two	LinkedIn company URL.
domain	string	One of two	Company domain (e.g. `acme.com`).

Example request

curl -X POST "https://api.getsillage.com/api/v2/top-account-list/accounts" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      { "domain": "acme.com" },
      { "linkedin_url": "https://www.linkedin.com/company/northstar", "domain": "northstar.io" }
    ]
  }'

Example response

{
  "tal_id": 17,
  "accounts": [
    { "domain": "acme.com" },
    {
      "linkedin_url": "https://www.linkedin.com/company/northstar",
      "domain": "northstar.io"
    }
  ],
  "message": "Top account list ingestion queued"
}

When the resulting list falls outside the recommended range, warnings appears in the response:

{
  "tal_id": 17,
  "accounts": [{ "domain": "acme.com" }],
  "message": "Top account list ingestion queued",
  "warnings": [
    "The top account list now has 2 account(s), below the recommended minimum of 5. Call sillage_v2_add_top_accounts to add more."
  ]
}

Response fields

Field	Type	Description
tal_id	integer	Top account list identifier.
accounts	array	Echo of the accounts submitted.
message	string	Confirmation message.
warnings	string[]	Non-blocking reminders about the resulting list, for example when its size falls outside the recommended 5 to 20 accounts. Omitted from the response when there is nothing to flag.

Tracking ingestion progress

The 202 confirms the accounts were accepted for ingestion. To track when account mapping enrichment for a specific account completes, poll the stage endpoint after you observe a content request for that account:

GET /api/v2/account-mapping/{id}/stage

Terminal stages: completed (success) and account_mapping_failed (failure). See Account Mapping — Polling enrichment stage for the full response shape and polling details.

Errors

Status	Meaning
400	The request body is invalid — missing/malformed fields, more than 10,000 accounts, or an account with neither `linkedin_url` nor `domain`.
401	The API key is missing or invalid.
403	Adding these accounts would exceed your workspace's limited trial quota. No accounts were added.
422	Your workspace has no persona with a location that resolves to a country. See Minimum setup required above.
429	Rate limit exceeded.
500	An unexpected server error occurred.

Error responses use RFC 9457 problem documents with Content-Type: application/problem+json. The quota error carries a dedicated type so you can detect it programmatically:

{
  "type": "https://docs.getsillage.com/errors/top-account-quota-exceeded",
  "title": "Top account quota exceeded",
  "status": 403,
  "detail": "Adding 50 accounts would exceed your remaining quota of 12.",
  "instance": "/api/v2/top-account-list/accounts"
}

Add Accounts

On this page