Using Signals API

Using the Signals API

Operations for managing and retrieving signals:

List signals - Get all signals with filtering options
Get signal by ID - Retrieve a specific signal's details
Contact research - Deep-dive analysis of individual contacts
Contact search - Find contacts at companies using LinkedIn Sales Navigator

For creating signals, see the "Creating a Signal" section which includes the recommended synchronous endpoints.

List all signals

get

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

Note: For getting completed signal results, we recommend using the /v1/companies/signals/sync endpoint instead, which provides a more efficient cursor-based approach.

Authorizations

AuthorizationstringRequired

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

Query parameters

domainstringOptional

Filter signals by company domain (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])?)*$

companyIdstringOptional

Filter signals by company ID

Example: comp_abc123

limitinteger · min: 1 · max: 25Optional

Maximum number of results per page

Default: 25Example: 25

offsetintegerOptional

Number of results to skip for pagination

Default: 0Example: 0

fromDatestring · date-timeOptional

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

Example: 2024-01-01T00:00:00Z

toDatestring · date-timeOptional

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

Example: 2024-12-31T23:59:59Z

Responses

200

Signals retrieved successfully

application/json

400

Bad Request - Invalid parameters

application/json

401

Unauthorized - Invalid or missing API key

application/json

500

Internal Server Error

application/json

get

/v1/companies/signals

GET /v1/companies/signals HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get signal status and results

get

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.

Authorizations

AuthorizationstringRequired

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

Path parameters

signalIdstringRequired

The unique identifier of the signal (UUID format)

Example: e45c1dc4-d422-4b51-956b-cb6d3ddaf250Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Responses

200

Signal retrieved successfully

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Signal not found or access denied

application/json

500

Internal Server Error

application/json

get

/v1/companies/signals/{signalId}

GET /v1/companies/signals/{signalId} HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Get contact research by external ID

get

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).

Authorizations

AuthorizationstringRequired

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

Query parameters

externalIdstring · min: 1 · max: 100Required

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

Example: hubspot_12345

externalSourcestring · min: 1 · max: 50Required

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

Example: hubspot

Responses

200

Contact research retrieved successfully

application/json

400

Bad Request - Missing required query parameters

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Not Found - Contact research not found or access denied

application/json

500

Internal Server Error

application/json

get

/v1/contacts/research

GET /v1/contacts/research?externalId=text&externalSource=text HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Create a new contact research request

post

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.

Authorizations

AuthorizationstringRequired

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

Body

firstNamestring · min: 1 · max: 100Required

First name of the contact

Example: John

lastNamestring · min: 1 · max: 100Required

Last name of the contact

Example: Doe

companyNamestring · min: 1 · max: 200Required

Name of the contact's company

Example: Acme Corp

companyDomainstring · min: 1 · max: 253Required

Company domain (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])?)*$

contactProfileUrlstring · uri · max: 500Optional

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

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

linkedInSalesNavigatorUrlstring · uri · max: 500Optional

LinkedIn Sales Navigator profile URL of the contact (optional)

Example: https://www.linkedin.com/sales/lead/ACwAAABcD...

jobTitlestring · min: 1 · max: 200Optional

Job title of the contact (optional)

Example: VP of Sales

webhookUrlstring · uri · max: 2048Optional

Optional webhook URL to receive notifications when processing completes

Example: https://myapp.com/webhooks/contact-research

Responses

201

Contact research request 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/research

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

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

Get contact research status and results

get

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

Authorizations

AuthorizationstringRequired

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

Path parameters

idstringRequired

The unique identifier of the contact research request

Example: cr_abc123def456

Responses

200

Contact research retrieved successfully

application/json

404

Not Found - Contact research not found or access denied

application/json

500

Internal Server Error

application/json

get

/v1/contacts/research/{id}

GET /v1/contacts/research/{id} HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

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

Search for contacts at a company

post

Search for contacts at a company using their LinkedIn company URL and various search parameters. This endpoint uses LinkedIn Sales Navigator to discover contacts matching the specified criteria.

Requirements:

A valid company LinkedIn URL is required
At least one search parameter (firstName, lastName, jobTitles, keywords, or countries) must be provided
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

Authorizations

AuthorizationstringRequired

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

Body

companyLinkedInUrlstring · uriRequired

LinkedIn company URL to search for contacts

Example: https://linkedin.com/company/google

firstNamestring · max: 100Optional

First name of the contact to search for

Example: John

lastNamestring · max: 100Optional

Last name of the contact to search for

Example: Doe

jobTitlesstring[]Optional

Job titles to search for

Example: ["Engineering Manager","VP Engineering"]

keywordsstring · max: 500Optional

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

Example: Kubernetes, DevOps

countriesstring[]Optional

Countries to filter contacts by location (ISO 3166-1 alpha-2 codes)

Example: ["US","GB","DE"]

Responses

200

Contact search completed successfully

application/json

400

Bad Request - Invalid input

application/json

401

Unauthorized - Invalid or missing API key

application/json

422

Unprocessable Entity - Could not process LinkedIn URL

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/contacts/search

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

{
  "companyLinkedInUrl": "https://linkedin.com/company/google",
  "jobTitles": [
    "Engineering Manager",
    "VP Engineering"
  ],
  "countries": [
    "United States"
  ]
}

{
  "contacts": [
    {
      "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"
    }
  ],
  "count": 2,
  "companyName": "Google",
  "salesNavConnected": true
}

List all contact signals

get

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

Note: For getting completed signal results, we recommend using the /v1/contacts/signals/sync endpoint instead, which provides a more efficient cursor-based approach.

Authorizations

AuthorizationstringRequired

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

Query parameters

contactProfileUrlstring · uriOptional

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

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

limitinteger · min: 1 · max: 25Optional

Maximum number of results per page

Default: 25Example: 25

offsetintegerOptional

Number of results to skip for pagination

Default: 0Example: 0

Responses

200

Contact signals retrieved successfully

application/json

400

Bad Request - Invalid parameters

application/json

401

Unauthorized - Invalid or missing API key

application/json

500

Internal Server Error

application/json

get

/v1/contacts/signals

GET /v1/contacts/signals HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
      "status": "pending",
      "domain": "acme.com",
      "question": "What is Acme Corp's main business focus?",
      "createdAt": "2024-01-15T10:30:00Z",
      "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": {
        "processingTime": "2m 15s",
        "sourcesAnalyzed": 12
      },
      "error": "Unable to access domain or insufficient information available",
      "changeContext": {
        "changeType": "CHANGED",
        "changeSummary": "Added 4 items, removed 5 items.",
        "changeDelta": {
          "type": "LIST",
          "added": [
            "Enterprise"
          ],
          "removed": [
            "Starter"
          ]
        },
        "previousSignalId": "feb2e1c1-dc67-49f6-a459-62383c67daf5"
      },
      "verificationLevel": "verified"
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1,
  "count": 1
}

Get contact signal status and results

get

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.

Authorizations

AuthorizationstringRequired

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

Path parameters

signalIdstringRequired

The unique identifier of the contact signal (UUID format)

Example: e45c1dc4-d422-4b51-956b-cb6d3ddaf250Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Responses

200

Contact signal retrieved successfully

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Signal not found or access denied

application/json

500

Internal Server Error

application/json

get

/v1/contacts/signals/{signalId}

GET /v1/contacts/signals/{signalId} HTTP/1.1
Host: api.saber.app
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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:30:05Z",
  "answer": {
    "type": "open_text",
    "openText": {
      "value": "Placeholder response"
    }
  },
  "reasoning": "This is a placeholder response for contact signals. Full implementation coming soon.",
  "confidence": 0,
  "sources": [],
  "metadata": {
    "companyName": "Contact Signal (Not Implemented)",
    "processingTimeMs": 5000
  }
}

PreviousCreating a Signal NextSignals Templates

Last updated 9 days ago