Signal Subscriptions

List all signal subscriptions for your organization

GET
/v1/companies/signals/subscriptions

Retrieve a paginated list of signal subscriptions. Each subscription is merged with its signal template data so the response includes the full template definition alongside the schedule configuration.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Query Parameters

limit?integer

Maximum number of subscriptions to return

Default20
Range1 <= value <= 100
offset?integer

Number of subscriptions to skip for pagination

Default0
Range0 <= value

Response Body

application/json

application/json

curl -X GET "https://example.com/v1/companies/signals/subscriptions"
{  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",      "version": 0,      "name": "string",      "description": "string",      "question": "string",      "answerType": "open_text",      "outputSchema": {},      "weight": "important",      "qualificationCriteria": {},      "frequency": "daily",      "cronExpression": "string",      "timezone": "string",      "status": "active",      "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",      "lastRunAt": "2019-08-24T14:15:22Z",      "nextRunAt": "2019-08-24T14:15:22Z",      "source": "string",      "createdAt": "2019-08-24T14:15:22Z"    }  ],  "total": 42,  "limit": 20,  "offset": 0,  "hasMore": false}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Create a signal subscription

POST
/v1/companies/signals/subscriptions

Create a subscription that schedules recurring signal executions.

You can either reference an existing template via signalTemplateId, or create a template inline by providing name and question (plus optional fields like answerType, description, weight, qualificationCriteria, outputSchema).

The subscription is created in a stopped state. Use the schedule lifecycle endpoints (POST .../start) to activate it.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

signalTemplateId?string

ID of an existing signal template. If omitted, name and question are required to create a template inline.

Formatuuid
name?string

Template name (required when creating inline, ignored when signalTemplateId is provided)

Length1 <= length <= 200
description?string

Template description (optional, for inline creation)

Lengthlength <= 1000
question?string

Research question (required when creating inline)

Length1 <= length <= 500
answerType?string

Expected answer format (for inline creation, defaults to open_text)

Default"open_text"
Value in"open_text" | "number" | "boolean" | "list" | "percentage" | "currency" | "url" | "contacts" | "contact_posts" | "contact_engagements" | "json_schema"
outputSchema?

JSON Schema for custom output (when answerType is json_schema)

weight?string

Importance of the signal (for inline creation)

Value in"important" | "nice_to_have" | "not_important"
qualificationCriteria?

Qualification criteria for scoring answers (for inline creation)

frequency?string

Preset schedule frequency. Mutually exclusive with cronExpression — exactly one must be provided.

Value in"daily" | "weekly" | "monthly"
cronExpression?string

Custom cron expression (5-field). Mutually exclusive with frequency — exactly one must be provided.

timezone?string

IANA timezone for scheduling (defaults to UTC)

listId*string

Contact list ID to scope signal execution

Formatuuid

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/companies/signals/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",  "version": 0,  "name": "string",  "description": "string",  "question": "string",  "answerType": "open_text",  "outputSchema": {},  "weight": "important",  "qualificationCriteria": {},  "frequency": "daily",  "cronExpression": "string",  "timezone": "string",  "status": "active",  "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",  "lastRunAt": "2019-08-24T14:15:22Z",  "nextRunAt": "2019-08-24T14:15:22Z",  "source": "string",  "createdAt": "2019-08-24T14:15:22Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Get a signal subscription by ID

GET
/v1/companies/signals/subscriptions/{subscriptionId}

Retrieve a single subscription merged with its signal template data.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

subscriptionId*string

The unique identifier of the subscription

Formatuuid

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/companies/signals/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",  "version": 0,  "name": "string",  "description": "string",  "question": "string",  "answerType": "open_text",  "outputSchema": {},  "weight": "important",  "qualificationCriteria": {},  "frequency": "daily",  "cronExpression": "string",  "timezone": "string",  "status": "active",  "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",  "lastRunAt": "2019-08-24T14:15:22Z",  "nextRunAt": "2019-08-24T14:15:22Z",  "source": "string",  "createdAt": "2019-08-24T14:15:22Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Update a signal subscription

PUT
/v1/companies/signals/subscriptions/{subscriptionId}

Update a subscription's schedule configuration and/or its underlying template fields. When schedule fields are provided, the active schedule is updated. When template fields are provided, the underlying signal template is updated inline.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

subscriptionId*string

The unique identifier of the subscription to update

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

frequency?string

Preset schedule frequency. Mutually exclusive with cronExpression.

Value in"daily" | "weekly" | "monthly"
cronExpression?string

Custom cron expression (5-field). Mutually exclusive with frequency.

timezone*string

IANA timezone for scheduling

name*string

The subscription display name

Length1 <= length <= 200
question*string

The research question

Length1 <= length <= 500
answerType*string

Expected answer format

Value in"open_text" | "number" | "boolean" | "list" | "percentage" | "currency" | "url" | "contacts" | "contact_posts" | "contact_engagements" | "json_schema"
description?string

Signal description

Lengthlength <= 1000
outputSchema?|

JSON schema for json_schema answer type. Send null to clear.

weight?string

Signal importance weight

Value in"important" | "nice_to_have" | "not_important"
qualificationCriteria?

Qualification criteria

Response Body

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/companies/signals/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "timezone": "America/New_York",    "name": "string",    "question": "string",    "answerType": "open_text"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",  "version": 0,  "name": "string",  "description": "string",  "question": "string",  "answerType": "open_text",  "outputSchema": {},  "weight": "important",  "qualificationCriteria": {},  "frequency": "daily",  "cronExpression": "string",  "timezone": "string",  "status": "active",  "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",  "lastRunAt": "2019-08-24T14:15:22Z",  "nextRunAt": "2019-08-24T14:15:22Z",  "source": "string",  "createdAt": "2019-08-24T14:15:22Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Start a signal subscription

POST
/v1/companies/signals/subscriptions/{subscriptionId}/start

Activate a stopped subscription. Begins recurring signal execution according to the subscription's cron expression.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

subscriptionId*string

The unique identifier of the subscription to start

Formatuuid

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/companies/signals/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/start"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",  "version": 0,  "name": "string",  "description": "string",  "question": "string",  "answerType": "open_text",  "outputSchema": {},  "weight": "important",  "qualificationCriteria": {},  "frequency": "daily",  "cronExpression": "string",  "timezone": "string",  "status": "active",  "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",  "lastRunAt": "2019-08-24T14:15:22Z",  "nextRunAt": "2019-08-24T14:15:22Z",  "source": "string",  "createdAt": "2019-08-24T14:15:22Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Stop a signal subscription

POST
/v1/companies/signals/subscriptions/{subscriptionId}/stop

Pause an active subscription so no further recurring executions occur. The subscription can be restarted later.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

subscriptionId*string

The unique identifier of the subscription to stop

Formatuuid

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/companies/signals/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/stop"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",  "version": 0,  "name": "string",  "description": "string",  "question": "string",  "answerType": "open_text",  "outputSchema": {},  "weight": "important",  "qualificationCriteria": {},  "frequency": "daily",  "cronExpression": "string",  "timezone": "string",  "status": "active",  "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",  "lastRunAt": "2019-08-24T14:15:22Z",  "nextRunAt": "2019-08-24T14:15:22Z",  "source": "string",  "createdAt": "2019-08-24T14:15:22Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

Trigger an immediate run of a signal subscription

POST
/v1/companies/signals/subscriptions/{subscriptionId}/trigger

Trigger an immediate execution of the subscription regardless of the cron schedule. Works for both active and stopped subscriptions.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

API key authentication using Bearer token. Format: sk_live_ followed by a secure random string.

In: header

Path Parameters

subscriptionId*string

The unique identifier of the subscription to trigger

Formatuuid

Response Body

application/json

application/json

application/json

curl -X POST "https://example.com/v1/companies/signals/subscriptions/497f6eca-6276-4993-bfeb-53cbbbba6f08/trigger"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "signalTemplateId": "81bb942d-4a88-42b6-b91c-b3e4585f194d",  "version": 0,  "name": "string",  "description": "string",  "question": "string",  "answerType": "open_text",  "outputSchema": {},  "weight": "important",  "qualificationCriteria": {},  "frequency": "daily",  "cronExpression": "string",  "timezone": "string",  "status": "active",  "listId": "9fc6ad7d-902a-4834-b161-a4911b883d44",  "lastRunAt": "2019-08-24T14:15:22Z",  "nextRunAt": "2019-08-24T14:15:22Z",  "source": "string",  "createdAt": "2019-08-24T14:15:22Z"}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}
{  "error": {    "type": "VALIDATION",    "code": "VALIDATION_ERROR",    "message": "validation failed for 'departments': invalid value: Engineering Ops",    "errorCode": "string",    "errorAction": "string",    "details": {},    "requestId": "e69ed773-2674-4dca-be61-886d6698f360",    "fields": [      {        "field": "domain",        "message": "'domain' must be a valid hostname (e.g., 'example.com') without protocol (https://) or path"      }    ],    "debug": {      "cause": "string"    }  }}

On this page

List all signal subscriptions for your organizationCreate a signal subscriptionGet a signal subscription by IDUpdate a signal subscriptionStart a signal subscriptionStop a signal subscriptionTrigger an immediate run of a signal subscription