Using Signals API

List company signals

GET
/v1/companies/signals

Retrieve all signals with optional filtering by domain or companyId, pagination and filtering. Results are sorted by creation date (latest first).

Note: For creating signals and getting results in one step, we recommend using the /v1/companies/signals/sync endpoint instead, which returns the result directly.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Query Parameters

domain?string

Filter signals by company domain (e.g., "acme.com")

Match^[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])?)*$
companyId?string

Filter signals by company ID

limit?integer

Maximum number of results per page

Default25
Range1 <= value <= 25
offset?integer

Number of results to skip for pagination

Default0
Range0 <= value
fromDate?string

Filter signals completed on or after this date (RFC3339 format)

Formatdate-time
toDate?string

Filter signals completed on or before this date (RFC3339 format)

Formatdate-time
status?array<>

Filter by signal status (can be specified multiple times for multiple statuses)

subscriptionId?string

Filter signals by subscription ID (UUID of the signal subscription that triggered execution)

Formatuuid

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/companies/signals?domain=acme.com&companyId=comp_abc123&limit=25&offset=0&fromDate=2024-01-01T00%3A00%3A00Z&toDate=2024-12-31T23%3A59%3A59Z&status=completed&subscriptionId=a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
{  "results": [    {      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",      "status": "completed",      "domain": "acme.com",      "question": "What is their main product?",      "createdAt": "2024-01-15T10:30:00Z",      "completedAt": "2024-01-15T10:32:00Z",      "answer": {        "type": "open_text",        "openText": {          "value": "Enterprise CRM software"        }      },      "confidence": 0.95    },    {      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",      "status": "processing",      "domain": "acme.com",      "question": "How many employees?",      "createdAt": "2024-01-15T09:00:00Z"    }  ],  "total": 42,  "limit": 25,  "offset": 0,  "count": 2}
{  "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"    }  }}

List signal executions for a subscription

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

Retrieve all signal executions that were triggered by a specific signal subscription. Returns the same paginated response as GET /v1/companies/signals but filtered to a single subscription. Results are sorted by creation date (latest first).

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 UUID of the signal subscription

Formatuuid

Query Parameters

domain?string

Filter signals by company domain

companyId?string

Filter signals by company ID

limit?integer

Maximum number of results per page

Default25
Range1 <= value <= 25
offset?integer

Number of results to skip for pagination

Default0
Range0 <= value
fromDate?string

Filter signals completed on or after this date (RFC3339 format)

Formatdate-time
toDate?string

Filter signals completed on or before this date (RFC3339 format)

Formatdate-time
status?array<>

Filter by signal status (can be specified multiple times)

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/companies/signals/subscriptions/a12b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/logs?domain=acme.com&companyId=b23c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e&limit=25&offset=0&fromDate=2024-01-01T00%3A00%3A00Z&toDate=2024-12-31T23%3A59%3A59Z&status=completed"
{  "results": [    {      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",      "status": "processing",      "question": "What is Acme Corp's main business focus?",      "answerType": "boolean",      "createdAt": "2024-01-15T10:30:00Z",      "signalType": "COMPANY",      "domain": "acme.com",      "completedAt": "2024-01-15T10:32:15Z",      "answer": {        "type": "open_text",        "open_text": {          "value": "Acme Corp is a leading provider of enterprise software solutions"        }      },      "reasoning": "Based on the company's website and public information, Acme Corp specializes in enterprise software.",      "confidence": 0.95,      "sources": [        {          "url": "https://acme.com/about",          "title": "About Acme Corp",          "snippet": "Leading provider of enterprise software..."        }      ],      "metadata": {        "companyName": "Acme Corp",        "processingTimeMs": 45200,        "connectors": {          "salesNavigator": {            "status": "ok"          }        }      },      "error": "LinkedIn data is currently unavailable due to rate limits. Please try again later.",      "errorCode": "LINKEDIN_RATE_LIMIT_EXCEEDED",      "errorAction": "You can: (1) Set connectors.salesNavigator.enabled=\"off\" to skip LinkedIn data, (2) Add more LinkedIn connectors, or (3) Try again in 24 hours when rate limits reset.",      "changeContext": {        "changeType": "CHANGED",        "changeDelta": {          "type": "LIST",          "added": [            "Enterprise"          ],          "removed": [            "Starter"          ]        },        "previousSignalId": "feb2e1c1-dc67-49f6-a459-62383c67daf5",        "changedFields": [          "certifications",          "contacts",          "headline"        ],        "addedFields": [          "contacts",          "certifications"        ],        "updatedFields": [          "headline",          "engagement.reactionCount"        ],        "removedFields": [          "positions"        ]      },      "verificationMode": "strict",      "company": {        "id": "comp_abc123",        "name": "Acme Corp",        "domain": "acme.com",        "industry": "Software",        "website": "https://acme.com",        "size": "51-200",        "type": "private",        "founded": 2015,        "city": "San Francisco",        "state": "California",        "countryCode": "US",        "handle": "acme-corp",        "linkedInId": 12345678,        "linkedInUrl": "https://www.linkedin.com/company/acme-corp",        "linkedInFollowers": 5200,        "employeeCount": 150,        "description": "Acme Corp is a leading provider of enterprise software solutions.",        "logoUrl": "https://media.licdn.com/dms/image/acme-logo.png"      }    }  ],  "total": 42,  "limit": 25,  "offset": 0,  "count": 25}
{  "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"    }  }}
{  "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 company signal by ID

GET
/v1/companies/signals/{signalId}

Retrieve the current status and results of a signal. If the signal is completed, the response will include the AI-generated answer, confidence score, and sources.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

signalId*string

The unique identifier of the signal (UUID format)

Match^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/companies/signals/e45c1dc4-d422-4b51-956b-cb6d3ddaf250"

{  "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",  "status": "processing",  "domain": "acme.com",  "question": "What is Acme Corp's main business focus?",  "createdAt": "2024-01-15T10:30:00Z"}

{  "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": "NOT_FOUND",  "message": "Signal not found or access denied"}
{  "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 contact research by external ID

GET
/v1/contacts/research

Retrieve a contact research request by external ID and external source. This endpoint allows you to look up contact research requests using identifiers from external systems (e.g., HubSpot contact ID).

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Query Parameters

externalId*string

The external identifier of the contact research request (e.g., HubSpot contact ID)

Length1 <= length <= 100
externalSource*string

The source system that provided the external ID (e.g., "hubspot")

Length1 <= length <= 50

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/research?externalId=hubspot_12345&externalSource=hubspot"

{  "id": "cr_abc123def456",  "status": "processing",  "firstName": "John",  "lastName": "Doe",  "companyName": "Acme Corp",  "companyDomain": "acme.com",  "createdAt": "2024-01-15T10:30:00Z"}

{  "error": "BAD_REQUEST",  "message": "Invalid JSON in request body"}
{  "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": "NOT_FOUND",  "message": "Contact research not found or access denied"}
{  "error": "VALIDATION_ERROR",  "message": "Query parameters externalId and externalSource are required"}
{  "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 contact research job

POST
/v1/contacts/research

Submit contact details to create a new contact research request. The AI will gather information from LinkedIn, email services, and other data sources to provide comprehensive contact insights.

The research will be processed asynchronously. Use the returned contact research ID to check status via the GET endpoint, or configure a webhook to receive completion notifications.

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.

firstName*string

First name of the contact

Length1 <= length <= 100
lastName*string

Last name of the contact

Length1 <= length <= 100
companyName*string

Name of the contact's company

Length1 <= length <= 200
companyDomain*string

Company domain (e.g., "acme.com")

Match^[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])?)*$
Length1 <= length <= 253
contactProfileUrl?string

Contact profile URL of the contact (e.g., LinkedIn or other professional profile, optional)

Formaturi
Lengthlength <= 500
linkedInSalesNavigatorUrl?string

LinkedIn Sales Navigator profile URL of the contact (optional)

Formaturi
Lengthlength <= 500
jobTitle?string

Job title of the contact (optional)

Length1 <= length <= 200
webhookUrl?string

Optional webhook URL to receive notifications when processing completes

Formaturi
Lengthlength <= 2048

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/contacts/research" \  -H "Content-Type: application/json" \  -d '{    "firstName": "John",    "lastName": "Doe",    "companyName": "Acme Corp",    "companyDomain": "acme.com",    "jobTitle": "VP of Sales"  }'
{  "id": "cr_abc123def456",  "status": "processing",  "createdAt": "2024-01-15T10:30:00Z"}
{  "error": "BAD_REQUEST",  "message": "Invalid JSON in request body"}
{  "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": "VALIDATION_ERROR",  "message": "Invalid request body",  "details": [    {      "field": "companyDomain",      "message": "must be a valid hostname"    }  ]}
{  "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 contact research by ID

GET
/v1/contacts/research/{id}

Retrieve a contact research request by ID, including its status and results if completed. This endpoint returns the current state of the research request.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

The unique identifier of the contact research request

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/research/cr_abc123def456"

{  "id": "cr_abc123def456",  "status": "processing",  "firstName": "John",  "lastName": "Doe",  "companyName": "Acme Corp",  "companyDomain": "acme.com",  "createdAt": "2024-01-15T10:30:00Z"}

{  "error": "NOT_FOUND",  "message": "Contact research not found or access denied"}
{  "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"    }  }}

Search contacts with LinkedIn Sales Navigator

POST
/v1/contacts/search

Search for contacts using LinkedIn Sales Navigator. Optionally scoped to one or more companies via companyLinkedInUrls. When multiple URLs are provided, each company is searched separately and results are merged and deduplicated.

Pagination: Use limit (default 25, max 100) and offset (default 0) in the request body to page through results. The response includes total, limit, offset, and hasMore to support cursor-free pagination.

Requirements:

  • At least one search parameter must be provided: companyLinkedInUrls, firstName, lastName, jobTitles, keywords, countries, departments, or seniorityLevels.
  • LinkedIn Sales Navigator connection is required for the API key owner

Response:

  • If Sales Navigator is not connected, returns salesNavConnected: false with empty contacts
  • If connected, returns matching contacts with profile information and pagination metadata

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.

companyLinkedInUrls*array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName*string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName*string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles*array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords*string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries*array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments*array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels?array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value
companyLinkedInUrls?array<>

LinkedIn company URLs to scope the search (note: plural — pass an array even for a single company). Supports multiple companies; results are merged and deduplicated. Omit to search across all companies.

firstName?string

First name of the contact to search for

Lengthlength <= 100
lastName?string

Last name of the contact to search for

Lengthlength <= 100
jobTitles?array<>

Job titles to search for (plural — pass an array)

keywords?string

Keywords to search for in contact profiles (e.g., skills, technologies)

Lengthlength <= 500
countries?array<>

Countries to filter contacts by location. Must be ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE") — full country names are not accepted.

departments?array<>

Department (function) filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

seniorityLevels*array<>

Seniority level filter using LinkedIn Sales Navigator taxonomy. Multiple values are OR'd together. Combined with other filters via AND. All values are treated as INCLUDED — exclusion is not currently supported.

limit?integer

Maximum number of contacts to return per page

Default25
Range1 <= value <= 100
offset?integer

Zero-based offset for pagination

Default0
Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/contacts/search" \  -H "Content-Type: application/json" \  -d '{    "companyLinkedInUrls": [      "https://linkedin.com/company/google"    ],    "jobTitles": [      "Engineering Manager",      "VP Engineering"    ],    "countries": [      "US"    ]  }'

{  "items": [    {      "firstName": "John",      "lastName": "Doe",      "fullName": "John Doe",      "role": "Engineering Manager",      "linkedInSalesNavigatorProfileUrl": "https://www.linkedin.com/sales/lead/ACwAAABOW1gBQZCU123",      "avatar": "https://media.licdn.com/...",      "location": "San Francisco, California"    },    {      "firstName": "Jane",      "lastName": "Smith",      "fullName": "Jane Smith",      "role": "VP of Engineering",      "linkedInSalesNavigatorProfileUrl": "https://www.linkedin.com/sales/lead/ACwAAABOW1gBQZCU456",      "location": "New York, New York"    }  ],  "total": 150,  "limit": 25,  "offset": 0,  "hasMore": true,  "salesNavConnected": true}

{  "error": {    "type": "BAD_REQUEST",    "code": "BAD_REQUEST",    "message": "Invalid request body",    "requestId": "e69ed773-2674-4dca-be61-886d6698f360"  }}
{  "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",    "requestId": "e69ed773-2674-4dca-be61-886d6698f360"  }}

{  "statusCode": 429,  "error": "Too Many Requests",  "message": "Rate limit exceeded",  "retryAfter": 45}
{  "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"    }  }}

List contact signals

GET
/v1/contacts/signals

Retrieve all contact signals with optional filtering by LinkedIn URL, pagination and filtering. Results are sorted by creation date (latest first).

Note: For creating contact signals and getting results in one step, we recommend using the /v1/contacts/signals/sync endpoint instead, which returns the result directly.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Query Parameters

contactProfileUrl?string

Filter signals by contact profile URL (LinkedIn or other professional profile)

Formaturi
limit?integer

Maximum number of results per page

Default25
Range1 <= value <= 25
offset?integer

Number of results to skip for pagination

Default0
Range0 <= value

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/signals?contactProfileUrl=https%3A%2F%2Flinkedin.com%2Fin%2Fjohndoe&limit=25&offset=0"
{  "results": [    {      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",      "status": "processing",      "question": "What is Acme Corp's main business focus?",      "answerType": "boolean",      "createdAt": "2024-01-15T10:30:00Z",      "signalType": "COMPANY",      "domain": "acme.com",      "completedAt": "2024-01-15T10:32:15Z",      "answer": {        "type": "open_text",        "open_text": {          "value": "Acme Corp is a leading provider of enterprise software solutions"        }      },      "reasoning": "Based on the company's website and public information, Acme Corp specializes in enterprise software.",      "confidence": 0.95,      "sources": [        {          "url": "https://acme.com/about",          "title": "About Acme Corp",          "snippet": "Leading provider of enterprise software..."        }      ],      "metadata": {        "companyName": "Acme Corp",        "processingTimeMs": 45200,        "connectors": {          "salesNavigator": {            "status": "ok"          }        }      },      "error": "LinkedIn data is currently unavailable due to rate limits. Please try again later.",      "errorCode": "LINKEDIN_RATE_LIMIT_EXCEEDED",      "errorAction": "You can: (1) Set connectors.salesNavigator.enabled=\"off\" to skip LinkedIn data, (2) Add more LinkedIn connectors, or (3) Try again in 24 hours when rate limits reset.",      "changeContext": {        "changeType": "CHANGED",        "changeDelta": {          "type": "LIST",          "added": [            "Enterprise"          ],          "removed": [            "Starter"          ]        },        "previousSignalId": "feb2e1c1-dc67-49f6-a459-62383c67daf5",        "changedFields": [          "certifications",          "contacts",          "headline"        ],        "addedFields": [          "contacts",          "certifications"        ],        "updatedFields": [          "headline",          "engagement.reactionCount"        ],        "removedFields": [          "positions"        ]      },      "verificationMode": "strict",      "company": {        "id": "comp_abc123",        "name": "Acme Corp",        "domain": "acme.com",        "industry": "Software",        "website": "https://acme.com",        "size": "51-200",        "type": "private",        "founded": 2015,        "city": "San Francisco",        "state": "California",        "countryCode": "US",        "handle": "acme-corp",        "linkedInId": 12345678,        "linkedInUrl": "https://www.linkedin.com/company/acme-corp",        "linkedInFollowers": 5200,        "employeeCount": 150,        "description": "Acme Corp is a leading provider of enterprise software solutions.",        "logoUrl": "https://media.licdn.com/dms/image/acme-logo.png"      }    }  ],  "total": 0,  "limit": 0,  "offset": 0,  "count": 0}
{  "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"    }  }}

Get a contact signal by ID

GET
/v1/contacts/signals/{signalId}

Retrieve the current status and results of a contact signal. If the signal is completed, the response will include the AI-generated answer, confidence score, and sources.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

signalId*string

The unique identifier of the contact signal (UUID format)

Match^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/contacts/signals/e45c1dc4-d422-4b51-956b-cb6d3ddaf250"
{  "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"    }  },  "reasoning": "Based on LinkedIn profile analysis, this person regularly engages with content about software engineering and AI/ML topics.",  "confidence": 0.9,  "sources": [    {      "url": "https://linkedin.com/in/johndoe",      "title": "John Doe - LinkedIn",      "snippet": "Passionate about building AI-powered developer tools..."    }  ]}
{  "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"    }  }}

Get remaining credit balance

GET
/v1/credits

Returns the remaining credits balance for your organization.

Use this endpoint to check how many credits you have available before running large batches or to monitor usage programmatically.

What Are Credits?

Each API call that generates a signal consumes credits:

  • Company signal (POST /v1/companies/signals/sync) — consumes 1 credit per signal
  • Contact signal (POST /v1/contacts/signals/sync) — consumes 1 credit per signal
  • Batch signals — consumes 1 credit per signal in the batch
  • Read-only operations (listing, getting, templates) — free, no credits consumed

Credits reset at the start of each billing period.

When to Use This Endpoint

  • Before large batches: Check that you have enough credits before submitting a bulk request
  • Monitoring dashboards: Poll periodically to display current usage
  • Conditional logic: Skip signal generation if credits are exhausted

Example

curl https://api.saber.app/v1/credits \  -H "Authorization: Bearer YOUR_API_KEY"

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/credits"

{  "remainingCredits": 58}

{  "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"    }  }}

On this page

List company signalsList signal executions for a subscriptionGet a company signal by IDGet contact research by external IDStart a contact research jobGet contact research by IDSearch contacts with LinkedIn Sales NavigatorList contact signalsGet a contact signal by IDGet remaining credit balance