Set up a signal

Creates a new signal setup. Name the signal with signal_template_id (from List signal templates), then answer its questions in parameters — validated against that signal's own setup.fields.

You can set up the same signal more than once, for example to watch it against two different lists, or with a different set of keywords each time. Each call creates its own, independent setup; signal_template_id does not have to be unique within your workspace.

Route

POST/api/v3/signal-setups

Access modes

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

Authorization: Bearer sk_live_...

Body parameters

Parameter	Type	Required	Description
signal_template_id	integer	Yes	The ID of the signal to set up, from `GET /v3/signal-templates`. This ID is specific to your environment.
name	string	No	Display name for the new setup. Defaults to the signal's own name.
parameters	object	No	The setup's own answers. Validated against the signal's `setup.fields`. Omit if that signal requires none. Carries `list_id` for a signal that watches a list.
schedule	object or null	No	`{ "cadence": "weekly" }` to run this setup on a weekly cadence, `null` to turn scheduling off.

Signals that watch a list

Some signals watch a list you have built — your competitors, your partners, the influencers in your space, your champions. Those signals ask for it: their setup.fields declares a list_id property, and lists it as required. The property carries an x-watchlist-type saying which kind of list it accepts, for example competitor.

Send the ID of one of your own lists of that type, from Lists. Nothing is created for you: a signal that watches a list is never set up without one, so you always know which list a signal is working from.

{
  "signal_template_id": 7,
  "parameters": { "list_id": 12, "scopes": ["discovery"] }
}

A list_id that is missing, unknown, not yours, or not of the type the signal watches is refused the same way, with 422 and the field named:

{
  "errors": {
    "list_id": ["must reference an existing competitor list in this workspace"]
  }
}

A setup keeps the list it was created on. See Update a signal setup.

A list attached only to business units other than your persona's cannot be used: it is refused with 409.

Persona required

Most signals look for people matching your persona, so they require one with at least one job_title and one location — set it with PUT /v3/persona first. Champion and job-posting signals are the exception: they can be set up without a persona.

Without it, the setup is refused with 422 and the title Persona incomplete. The detail tells you what to add:

{
  "type": "about:blank",
  "title": "Persona incomplete",
  "status": 422,
  "detail": "This workspace's persona is missing location. Add it before setting up this signal.",
  "instance": "/api/v3/signal-setups"
}

Example request

curl -X POST "https://api.getsillage.com/api/v3/signal-setups" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signal_template_id": 3,
    "name": "Acme keywords",
    "parameters": { "keywords": ["acme"], "scopes": ["discovery"] }
  }'

Success response

Status: 201 Created

{
  "data": {
    "id": 42,
    "signal_template_id": 3,
    "name": "Acme keywords",
    "status": "enabled",
    "parameters": { "keywords": ["acme"], "scopes": ["discovery"] },
    "schedule": null,
    "created_at": "2026-09-18T12:00:00.000Z"
  }
}

Response fields

Field	Type	Description
data.id	integer	ID of the signal setup. Specific to your environment.
data.signal_template_id	integer	ID of the signal this setup is for.
data.name	string	Display name for this setup.
data.status	string	`enabled` or `disabled`.
data.parameters	object	Exactly what you sent. Update a signal setup merges changes into it — you never resend the whole object.
data.schedule	object or null	`null`, or `{ "cadence": "weekly" }` when this setup runs on its own.
data.created_at	string	When this setup was created.

Errors

Status	Meaning
401	The API key is missing or invalid.
404	No signal matches `signal_template_id`.
409	This signal cannot be set up yet, or is retired — or `list_id` is attached only to business units other than your persona's.
422	`parameters` fails validation against the signal's `setup.fields`, `list_id` included — or your persona is missing or incomplete (see Persona required).
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 on v3 — title is what tells one problem from another. A 422 names the offending property under errors:

{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Invalid setup parameters",
  "instance": "/api/v3/signal-setups",
  "errors": {
    "scopes": ["must have required property 'scopes'"]
  }
}

Set up a signal

On this page