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 company signals with optional filters for domain, company ID, date range, and status

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

ApiKeyAuth

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

subscriptionIdstring · uuidOptional

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

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

Responses

200

Signals retrieved successfully

application/json

totalintegerRequired

Total number of signals matching the filters

Example: 42

limitintegerRequired

Maximum results per page

Example: 25

offsetintegerRequired

Number of results skipped

Example: 0

countintegerRequired

Number of results in this response

Example: 25

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

HTTPcURLJavaScriptPython

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
}

List signal executions for a specific subscription

get

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

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Path parameters

subscriptionIdstring · uuidRequired

The UUID of the signal subscription

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

Query parameters

domainstringOptional

Filter signals by company domain

Example: acme.com

companyIdstringOptional

Filter signals by company ID

Example: b23c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e

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

Subscription logs retrieved successfully

application/json

totalintegerRequired

Total number of signals matching the filters

Example: 42

limitintegerRequired

Maximum results per page

Example: 25

offsetintegerRequired

Number of results skipped

Example: 0

countintegerRequired

Number of results in this response

Example: 25

400

Bad Request - Invalid subscription ID format

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Not Found - Subscription does not exist or does not belong to this organization

application/json

500

Internal Server Error

application/json

get

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

HTTPcURLJavaScriptPython

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

{
  "results": [
    {
      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
      "signalType": "COMPANY",
      "status": "processing",
      "question": "What is Acme Corp's main business focus?",
      "answerType": "boolean",
      "createdAt": "2024-01-15T10:30:00Z",
      "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
}

Get a company signal by ID — returns current status and AI-generated answer if completed

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

ApiKeyAuth

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

anyOptional

Polymorphic signal response (company or contact)

or

and

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}

HTTPcURLJavaScriptPython

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": "processing",
  "domain": "acme.com",
  "question": "What is Acme Corp's main business focus?",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get contact research using an external system's ID (e.g. a HubSpot contact ID) and source name

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

ApiKeyAuth

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

idstringRequired

Unique identifier for the contact research request

Example: cr_abc123def456

statusstring · enumRequired

Current processing status of the contact research

Example: completedPossible values:

firstNamestringRequired

First name of the contact

Example: John

lastNamestringRequired

Last name of the contact

Example: Doe

companyNamestringRequired

Company name

Example: Acme Corp

companyDomainstringRequired

Company domain

Example: acme.com

createdAtstring · date-timeRequired

Timestamp when the research request was created

Example: 2024-01-15T10:30:00Z

contactProfileUrlstringOptional

Contact profile URL if provided (e.g., LinkedIn or other professional profile)

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

jobTitlestringOptional

Job title - prioritizes the title found during research (profile.currentRole), falls back to the title provided in the request if research didn't find one

Example: VP of Sales

interestsstring[]Optional

Professional interests and topics (only present when status is "completed")

challengesstring[]Optional

Potential challenges or pain points (only present when status is "completed")

errorstringOptional

Error message if status is "failed"

Example: Could not retrieve LinkedIn profile data

completedAtstring · date-timeOptional

Timestamp when the research completed (success or failure)

Example: 2024-01-15T10:35:00Z

400

Bad Request - Malformed request body

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Not Found - Contact research not found or access denied

application/json

422

Unprocessable Entity - Validation error

application/json

500

Internal Server Error

application/json

get

/v1/contacts/research

HTTPcURLJavaScriptPython

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

Start a contact research job — AI gathers insights from LinkedIn and other sources asynchronously; use contacts.get_research to poll for results

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

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

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 - Malformed request body (invalid JSON)

application/json

401

Unauthorized - Invalid or missing API key

application/json

422

Unprocessable Entity - Validation error

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

post

/v1/contacts/research

HTTPcURLJavaScriptPython

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

Basic contact research requestRequest with LinkedIn URLRequest with Sales Navigator URL

{
  "id": "cr_abc123def456",
  "status": "processing",
  "createdAt": "2024-01-15T10:30:00Z"
}

Get contact research by ID — returns status and AI-generated insights if completed

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

ApiKeyAuth

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

idstringRequired

Unique identifier for the contact research request

Example: cr_abc123def456

statusstring · enumRequired

Current processing status of the contact research

Example: completedPossible values:

firstNamestringRequired

First name of the contact

Example: John

lastNamestringRequired

Last name of the contact

Example: Doe

companyNamestringRequired

Company name

Example: Acme Corp

companyDomainstringRequired

Company domain

Example: acme.com

createdAtstring · date-timeRequired

Timestamp when the research request was created

Example: 2024-01-15T10:30:00Z

contactProfileUrlstringOptional

Contact profile URL if provided (e.g., LinkedIn or other professional profile)

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

jobTitlestringOptional

Job title - prioritizes the title found during research (profile.currentRole), falls back to the title provided in the request if research didn't find one

Example: VP of Sales

interestsstring[]Optional

Professional interests and topics (only present when status is "completed")

challengesstring[]Optional

Potential challenges or pain points (only present when status is "completed")

errorstringOptional

Error message if status is "failed"

Example: Could not retrieve LinkedIn profile data

completedAtstring · date-timeOptional

Timestamp when the research completed (success or failure)

Example: 2024-01-15T10:35:00Z

404

Not Found - Contact research not found or access denied

application/json

500

Internal Server Error

application/json

get

/v1/contacts/research/{id}

HTTPcURLJavaScriptPython

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 via LinkedIn Sales Navigator — requires a LinkedIn Sales Navigator connection on the API key owner's account

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

ApiKeyAuth

AuthorizationstringRequired

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

Body

application/json

companyLinkedInUrlsstring · uri[]Optional

LinkedIn company URLs to scope the search. Supports multiple companies. Omit to search across all companies.

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

countintegerRequired

Total number of contacts found

Example: 15

salesNavConnectedbooleanRequired

Whether LinkedIn Sales Navigator is connected for the user

Example: true

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

HTTPcURLJavaScriptPython

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

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

Search by job titles at a companySearch across multiple companiesSearch by name (no company scope)Search by keywords at a company

{
  "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,
  "salesNavConnected": true
}

List contact signals with optional filters for LinkedIn profile URL and pagination

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

ApiKeyAuth

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

totalintegerOptional

limitintegerOptional

offsetintegerOptional

countintegerOptional

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

HTTPcURLJavaScriptPython

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

{
  "results": [
    {
      "id": "e45c1dc4-d422-4b51-956b-cb6d3ddaf250",
      "signalType": "COMPANY",
      "status": "processing",
      "question": "What is Acme Corp's main business focus?",
      "answerType": "boolean",
      "createdAt": "2024-01-15T10:30:00Z",
      "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": 1,
  "limit": 1,
  "offset": 1,
  "count": 1
}

Get a contact signal by ID — returns current status and AI-generated answer if completed

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

ApiKeyAuth

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

Polymorphic signal response (company or contact)

completedAtstring · date-timeOptional

When the signal processing completed (only present when status is completed)

Example: 2024-01-15T10:32:15Z

answerone ofOptional

The AI-generated answer (only present when status is completed)

or

or

or

or

or

or

or

or

or

or

reasoningstringOptional

Detailed reasoning for the answer (only present when status is completed)

Example: Based on the company's website and public information, Acme Corp specializes in enterprise software.

confidencenumber · float · max: 1Optional

Confidence score for the answer (0-1, only present when status is completed)

Example: 0.95

errorstringOptional

Error message (only present when status is failed)

Example: LinkedIn data is currently unavailable due to rate limits. Please try again later.

errorCodestring · enumOptional

Machine-readable error code (only present when status is failed)

Example: LINKEDIN_RATE_LIMIT_EXCEEDEDPossible values:

errorActionstringOptional

Suggested action to resolve the error (only present when status is failed)

Example: 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.

verificationModestring · enumOptional

Verification mode used for signal generation

Example: strictPossible values:

contactProfileUrlstring · uriOptional

Contact profile URL (LinkedIn or other professional profile)

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

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}

HTTPcURLJavaScriptPython

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

Get remaining credits balance — returns how many API credits your organization has left in the current billing period

get

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"

Authorizations

ApiKeyAuth

AuthorizationstringRequired

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

Responses

200

Credit balance retrieved successfully

application/json

Remaining credits balance for the organization in the current billing period

remainingCreditsintegerRequired

Number of credits remaining in the current billing period. Each signal creation consumes one credit. Returns 0 when the organization has no credits left; credits reset at the start of each new billing period.

Example: 58

401

Unauthorized - Invalid or missing API key

application/json

429

Too Many Requests - Rate limit exceeded

application/json

500

Internal Server Error

application/json

get

/v1/credits

HTTPcURLJavaScriptPython

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

{
  "remainingCredits": 58
}