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.

Creating and managing subscriptions is free. Each scheduled or triggered run generates signals, and every freshly generated signal charges 2 credits — the same pricing and caching rules as POST /v1/companies/signals.

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.

The trigger itself is free. Every signal the run freshly generates charges 2 credits (same pricing and caching rules as POST /v1/companies/signals); results served from cache are free.

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