Creating a Signal

What is a Signal?

A Signal is an AI-powered research request that answers a specific question about a company or contact. Think of it as asking an AI research assistant to investigate and provide verified answers with sources.

When you create a signal, Saber's AI:

🔍 Researches the target (company website, LinkedIn, public data sources)
🤖 Analyzes the information using advanced AI models
✅ Verifies findings against multiple sources
📊 Structures the answer in your requested format
🔗 Provides confidence scores and source citations

Signals support multiple answer types: text, numbers, booleans, lists, percentages, currency, URLs, and contacts.

Creating Signals

Company Signals analyze company domains to answer business intelligence questions like:

Technology stack and tools used
Company size, funding, and growth metrics
Market positioning and competitors
Products and services offered

Contact Signals analyze LinkedIn profiles to answer questions about individuals:

Professional interests and expertise
Career history and experience
Engagement and activity patterns
Communication preferences

Batch Creation allows you to efficiently create multiple signals at once using templates.

Create and wait for signal completion (Recommended)

post

⭐ This is the recommended way to create signals and get results instead of async + webhooks.

Creates a signal and waits synchronously for it to complete, returning the result in the same request. This endpoint blocks until the signal processing finishes or a timeout is reached.

Why Use the Sync Endpoint?

Advantages over async + webhooks:

✅ Get results immediately in one request
✅ No webhook hosting required
✅ No polling implementation needed
✅ Simpler integration
✅ Better for synchronous workflows

How It Works

Send your signal creation request (same payload as regular POST /v1/companies/signals)
The endpoint creates the signal and polls for completion
Returns the completed signal with results when processing finishes
If timeout is reached, returns the latest status (processing/pending)

Timeout Configuration

Default timeout: Configured per API key
Max timeout: 300 seconds (5 minutes)
Custom timeout: Use X-Sbr-Timeout-Sec header to set custom timeout (up to max)
Error on timeout: Use X-Sbr-Timeout-Error: true header to return 408 on timeout instead of latest status

Response Codes

200 OK - Signal completed successfully
202 Accepted - Timeout reached, signal still processing
408 Request Timeout - Timeout reached (when X-Sbr-Timeout-Error: true)

Using with Templates

Use signalTemplateId instead of defining questions inline for standardized research:

{
  "domain": "acme.com",
  "signalTemplateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

Templates let you reuse research questions, qualification criteria, and answer types across multiple companies. Create templates via POST /v1/companies/signals/templates.

Authorizations

AuthorizationstringRequired

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

Header parameters

X-Sbr-Timeout-Secinteger · min: 1 · max: 300Optional

Custom timeout in seconds (max 300). Defaults to your API key's configured timeout.

Example: 120

X-Sbr-Timeout-Errorstring · enumOptional

If "true", returns 408 Request Timeout on timeout instead of 202 with latest status

Example: falsePossible values:

Body

domainstring · min: 1 · max: 253Required

The company domain to research (e.g., "acme.com")

Example: acme.comPattern: ^[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?)*$

questionstring · min: 1 · max: 500Required

The research question to ask about the company

Example: What is Acme Corp's main business focus?

answerTypestring · enumOptional

The expected format of the answer

Default: open_textExample: open_textPossible values:

webhookUrlstring · uri · max: 2048Optional

Optional webhook URL to receive notifications when processing completes

Example: https://myapp.com/webhooks/signals

weightstring · enumOptional

The importance/weight of the signal

Example: importantPossible values:

signalTemplateIdstring · uuidOptional

Optional signal template ID to use. When provided, the template configuration (question, answerType, weight, qualificationCriteria) will be used. The system always resolves to the latest active version of the template. Only the domain parameter is required when using a template.

Example: a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

forceRefreshbooleanOptional

Force re-run of the signal analysis, skipping the cache. When set to true, a new signal will be created even if a cached result exists.

Default: falseExample: false

verificationModestring · enumOptional

Controls how strictly Saber verifies answers before responding.

strict: Only returns answers backed by verified sources (primary sources or trusted secondary sources like Crunchbase, PitchBook). Returns null when information is unavailable.
lenient: Allows logical inference and best-effort estimates when direct evidence is missing. Uses industry benchmarks, logical correlates, and quantitative metrics.

Default: strictExample: strictPossible values:

Responses

200

Signal completed successfully

application/json

202

Timeout reached - signal still processing

application/json

400

Bad Request - Invalid input

application/json

401

Unauthorized - Invalid or missing API key

application/json

408

Request Timeout - Signal processing exceeded timeout (only when X-Sbr-Timeout-Error header is set to true)

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/companies/signals/sync

POST /v1/companies/signals/sync HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "domain": "clay.com",
  "question": "Does this company have open roles in operations?",
  "answerType": "boolean"
}

{
  "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
  "status": "completed",
  "domain": "clay.com",
  "question": "Does this company have open roles in operations?",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:15Z",
  "answer": {
    "type": "boolean",
    "boolean": {
      "value": true
    }
  },
  "reasoning": "Based on their careers page, Clay has multiple open positions in Operations including Operations Manager and Operations Coordinator roles",
  "confidence": 0.95,
  "sources": [
    {
      "url": "https://clay.com/careers",
      "title": "Careers at Clay",
      "snippet": "We're hiring for Operations Manager and Operations Coordinator roles..."
    }
  ]
}

Create a new signal with webhook

post

Submit a domain and question to create a new research signal. The AI will analyze the domain and provide a structured answer based on the specified answer type.

When to Use This Endpoint

Use this endpoint for event-driven architectures where you need webhook notifications. For simpler integrations, use the /v1/companies/signals/sync endpoint (recommended) which returns results immediately.

Webhooks

Configure webhooks by including a webhookUrl parameter in your request.

Webhook events:

signal.completed - Signal processing finished successfully
signal.failed - Signal processing failed

Webhook security: All webhooks include HMAC-SHA256 signatures in the X-Webhook-Signature header for verification.

Webhook reliability:

Failed deliveries are retried up to 25 times with exponential backoff
Webhook requests timeout after 30 seconds
Your endpoint should respond with 2xx status code

Caching Behavior

Your response will be cached for up to 12 hours by default, unless you set the forceRefresh flag to true.

Cache is based on the company domain and question, so if you change the question or domain, a totally new signal will be created. We will not send you the webhook if you hit the cache, even if the webhook URL in the payload is different from the original request.

Instead you will receive the latest status of the signal immediately in the response.

Using with Templates

Use signalTemplateId instead of defining questions inline for standardized research:

{
  "domain": "acme.com",
  "signalTemplateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "webhookUrl": "https://myapp.com/webhooks/signals"
}

Templates let you reuse research questions, qualification criteria, and answer types across multiple companies. Create templates via POST /v1/companies/signals/templates.

Authorizations

AuthorizationstringRequired

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

Body

domainstring · min: 1 · max: 253Required

The company domain to research (e.g., "acme.com")

Example: acme.comPattern: ^[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?)*$

questionstring · min: 1 · max: 500Required

The research question to ask about the company

Example: What is Acme Corp's main business focus?

answerTypestring · enumOptional

The expected format of the answer

Default: open_textExample: open_textPossible values:

webhookUrlstring · uri · max: 2048Optional

Optional webhook URL to receive notifications when processing completes

Example: https://myapp.com/webhooks/signals

weightstring · enumOptional

The importance/weight of the signal

Example: importantPossible values:

signalTemplateIdstring · uuidOptional

Example: a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

forceRefreshbooleanOptional

Force re-run of the signal analysis, skipping the cache. When set to true, a new signal will be created even if a cached result exists.

Default: falseExample: false

verificationModestring · enumOptional

Controls how strictly Saber verifies answers before responding.

strict: Only returns answers backed by verified sources (primary sources or trusted secondary sources like Crunchbase, PitchBook). Returns null when information is unavailable.
lenient: Allows logical inference and best-effort estimates when direct evidence is missing. Uses industry benchmarks, logical correlates, and quantitative metrics.

Default: strictExample: strictPossible values:

Responses

201

Signal created successfully

application/json

400

Bad Request - Invalid input

application/json

401

Unauthorized - Invalid or missing API key

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/companies/signals

POST /v1/companies/signals HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 147

{
  "domain": "clay.com",
  "question": "What is Clay's main product offering?",
  "answerType": "open_text",
  "webhookUrl": "https://myapp.com/webhooks/signals"
}

{
  "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
  "status": "pending",
  "domain": "clay.com",
  "question": "What is Clay's main product offering?",
  "createdAt": "2024-01-15T10:30:00Z"
}

Create multiple signals in batch

post

Submit multiple signals and domains to create signals using a Cartesian product pattern. Each signal is combined with each domain to create individual signals.

Two ways to create batch signals:

Inline Questions: Define questions directly in the request for ad-hoc research without creating templates
Using Templates (recommended for reusability): Reference pre-created templates by ID for consistent, reusable questions

Cartesian Product Logic:

If you submit 2 templates and 3 domains, the system creates 6 signals (2 × 3)
Maximum 100 resulting signals allowed (templates × domains ≤ 100)
Signals beyond the 100 limit will throw an error

Partial Failure Handling:

Individual signal failures don't block other signals from processing
Each signal in the response includes its own status (accepted or failed)
Returns 202 if at least one signal is scheduled successfully
Returns 422 if all signals failed to be scheduled

Processing:

All signals are processed asynchronously
No guarantee of processing order
Use the /v1/companies/signals/sync endpoint (recommended) to retrieve results as they complete

Automatic Summary Generation:

Set generateSummaryOnComplete to true to automatically generate summaries when all signals in the batch complete
Summaries are generated per domain (one summary per unique domain in the batch)
Summary generation is triggered automatically once all signals for a domain have completed
Use the /v1/companies/signals/summaries endpoint to retrieve generated summaries

Authorizations

AuthorizationstringRequired

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

Body

domainsstring[] · min: 1 · max: 100Required

Array of company domains to research. Each domain will be combined with each signal template using Cartesian product logic. The total resulting signals (len(signals) × len(domains)) must not exceed 100.

Example: acme.com

generateSummaryOnCompletebooleanOptional

Whether to automatically generate a summary when all signals in the batch are completed. When set to true, a summary will be automatically generated for each unique domain in the batch once all signals for that domain have completed processing.

Default: falseExample: false

Responses

202

Batch accepted - At least one signal successfully scheduled

application/json

400

Bad Request - Invalid input

application/json

401

Unauthorized - Invalid or missing API key

application/json

422

Unprocessable Entity - All signals in batch failed to be scheduled

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/companies/signals/batch

POST /v1/companies/signals/batch HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 360

{
  "signals": [
    {
      "question": "What is their main product offering?",
      "answerType": "open_text",
      "weight": "important"
    },
    {
      "question": "How many employees do they have?",
      "answerType": "number",
      "weight": "nice_to_have"
    },
    {
      "question": "Are they venture-backed?",
      "answerType": "boolean",
      "weight": "important"
    }
  ],
  "domains": [
    "acme.com",
    "techcorp.io"
  ],
  "generateSummaryOnComplete": false
}

{
  "batchId": "batch_abc123def456",
  "submittedAt": "2024-01-15T10:30:00Z",
  "totalSignals": 6,
  "accepted": 5,
  "rejected": 1,
  "results": [
    {
      "templateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
      "status": "pending",
      "domain": "saber.app",
      "question": "What is their main product?",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "templateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "id": "f56d2ec5-e533-4c62-a67c-dc7d4eeaf361",
      "status": "pending",
      "domain": "google.com",
      "question": "What is their main product?",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "templateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "status": "failed",
      "domain": "stripe.com",
      "question": "What is their main product?",
      "error": "Invalid template configuration"
    },
    {
      "templateId": "b23c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "id": "a67d3fc6-f644-5d73-b78d-ed8e5ffbg472",
      "status": "pending",
      "domain": "saber.app",
      "question": "Are they hiring engineers?",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "templateId": "b23c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "id": "b78e4gd7-g755-6e84-c89e-fe9f6ggch583",
      "status": "pending",
      "domain": "google.com",
      "question": "Are they hiring engineers?",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "templateId": "b23c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
      "id": "c89f5he8-h866-7f95-d90f-gf0g7hhdi694",
      "status": "pending",
      "domain": "stripe.com",
      "question": "Are they hiring engineers?",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Create and wait for contact signal completion (Recommended)

post

⭐ This is the recommended way to create contact signals and get results instead of async + webhooks.

Creates a contact signal and waits synchronously for it to complete, returning the result in the same request. Works identically to the company signals sync endpoint but for contact-based signals.

Why Use the Sync Endpoint?

Advantages over async + webhooks:

✅ Get results immediately in one request
✅ No webhook hosting required
✅ No polling implementation needed
✅ Simpler integration
✅ Better for synchronous workflows

How It Works

Send your signal creation request (same payload as regular POST /v1/contacts/signals)
The endpoint creates the signal and polls for completion
Returns the completed signal with results when processing finishes
If timeout is reached, returns the latest status (processing/pending)

Timeout Configuration

Default timeout: Configured per API key
Max timeout: 300 seconds (5 minutes)
Custom timeout: Use X-Sbr-Timeout-Sec header to set custom timeout (up to max)
Error on timeout: Use X-Sbr-Timeout-Error: true header to return 408 on timeout instead of latest status

Response Codes

200 OK - Signal completed successfully
202 Accepted - Timeout reached, signal still processing
408 Request Timeout - Timeout reached (when X-Sbr-Timeout-Error: true)

Using with Templates

Use signalTemplateId instead of defining questions inline for standardized research:

{
  "contactProfileUrl": "https://linkedin.com/in/johndoe",
  "signalTemplateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

Templates let you reuse research questions, qualification criteria, and answer types across multiple contacts. Create templates via POST /v1/companies/signals/templates.

Authorizations

AuthorizationstringRequired

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

Header parameters

X-Sbr-Timeout-Secinteger · min: 1 · max: 300Optional

Custom timeout in seconds (max 300). Defaults to your API key's configured timeout.

Example: 120

X-Sbr-Timeout-Errorstring · enumOptional

If "true", returns 408 Request Timeout on timeout instead of 202 with latest status

Example: falsePossible values:

Body

contactProfileUrlstring · uri · min: 1 · max: 500Required

The contact profile URL to research (e.g., "https://linkedin.com/in/johndoe")

Example: https://linkedin.com/in/johndoe

questionstring · min: 1 · max: 500Required

The research question to ask about the contact

Example: What are this person's main professional interests?

answerTypestring · enumOptional

The expected format of the answer

Default: open_textExample: open_textPossible values:

webhookUrlstring · uri · max: 2048Optional

Optional webhook URL to receive notifications when processing completes

Example: https://myapp.com/webhooks/signals

weightstring · enumOptional

The importance/weight of the signal

Example: importantPossible values:

signalTemplateIdstring · uuidOptional

Optional signal template ID to use

Example: a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

verificationModestring · enumOptional

Controls how strictly Saber verifies answers before responding.

strict: Only returns answers backed by verified sources (primary sources or trusted secondary sources like Crunchbase, PitchBook). Returns null when information is unavailable.
lenient: Allows logical inference and best-effort estimates when direct evidence is missing. Uses industry benchmarks, logical correlates, and quantitative metrics.

Default: strictExample: strictPossible values:

Responses

200

Signal completed successfully

application/json

202

Timeout reached - signal still processing

application/json

400

Bad Request - Invalid input

application/json

401

Unauthorized - Invalid or missing API key

application/json

408

Request Timeout - Signal processing exceeded timeout (only when X-Sbr-Timeout-Error header is set to true)

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/contacts/signals/sync

POST /v1/contacts/signals/sync HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 145

{
  "contactProfileUrl": "https://linkedin.com/in/johndoe",
  "question": "What are this person's main professional interests?",
  "answerType": "open_text"
}

{
  "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
  "status": "completed",
  "contactProfileUrl": "https://linkedin.com/in/johndoe",
  "question": "What are this person's main professional interests?",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:32:15Z",
  "answer": {
    "type": "open_text",
    "openText": {
      "value": "Software engineering, AI/ML, and developer tools"
    }
  },
  "confidence": 0.9
}

Create a new contact signal with webhook

post

Submit a LinkedIn URL and question to create a new research signal for an individual contact. The AI will analyze the contact's profile and provide a structured answer based on the specified answer type.

Contact signals work similarly to company signals but focus on individual contacts using their LinkedIn profile URLs.

When to Use This Endpoint

Use this endpoint for event-driven architectures where you need webhook notifications. For simpler integrations, use the /v1/contacts/signals/sync endpoint (recommended) which returns results immediately.

Webhooks

Configure webhooks by including a webhookUrl parameter in your request.

Webhook events:

signal.completed - Signal processing finished successfully
signal.failed - Signal processing failed

Webhook security: All webhooks include HMAC-SHA256 signatures in the X-Webhook-Signature header for verification.

Webhook reliability:

Failed deliveries are retried up to 25 times with exponential backoff
Webhook requests timeout after 30 seconds
Your endpoint should respond with 2xx status code

Using with Templates

Use signalTemplateId instead of defining questions inline for standardized research:

{
  "contactProfileUrl": "https://linkedin.com/in/johndoe",
  "signalTemplateId": "a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "webhookUrl": "https://myapp.com/webhooks/signals"
}

Templates let you reuse research questions, qualification criteria, and answer types across multiple contacts. Create templates via POST /v1/companies/signals/templates.

Note: Contact signals currently return placeholder data and will be fully implemented in a future release.

Authorizations

AuthorizationstringRequired

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

Body

contactProfileUrlstring · uri · min: 1 · max: 500Required

The contact profile URL to research (e.g., "https://linkedin.com/in/johndoe")

Example: https://linkedin.com/in/johndoe

questionstring · min: 1 · max: 500Required

The research question to ask about the contact

Example: What are this person's main professional interests?

answerTypestring · enumOptional

The expected format of the answer

Default: open_textExample: open_textPossible values:

webhookUrlstring · uri · max: 2048Optional

Optional webhook URL to receive notifications when processing completes

Example: https://myapp.com/webhooks/signals

weightstring · enumOptional

The importance/weight of the signal

Example: importantPossible values:

signalTemplateIdstring · uuidOptional

Optional signal template ID to use

Example: a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d

verificationModestring · enumOptional

Controls how strictly Saber verifies answers before responding.

strict: Only returns answers backed by verified sources (primary sources or trusted secondary sources like Crunchbase, PitchBook). Returns null when information is unavailable.
lenient: Allows logical inference and best-effort estimates when direct evidence is missing. Uses industry benchmarks, logical correlates, and quantitative metrics.

Default: strictExample: strictPossible values:

Responses

201

Contact signal created successfully

application/json

400

Bad Request - Invalid input

application/json

401

Unauthorized - Invalid or missing API key

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/contacts/signals

POST /v1/contacts/signals HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 195

{
  "contactProfileUrl": "https://linkedin.com/in/johndoe",
  "question": "What are this person's main professional interests?",
  "answerType": "open_text",
  "webhookUrl": "https://myapp.com/webhooks/signals"
}

{
  "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
  "status": "pending",
  "contactProfileUrl": "https://linkedin.com/in/johndoe",
  "question": "What are this person's main professional interests?",
  "createdAt": "2024-01-15T10:30:00Z"
}

PreviousAuthentication NextUsing Signals API

Last updated 9 days ago