> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/intelligence/signals.md).

# Signals

Search Sumble Signals across the accounts available to your API key. Signals include champion movements, recent hires and promotions, technology and product mentions, projects and initiatives, and technology or job function trends.

Use this endpoint when you want a filtered feed across many accounts. If you already have one Sumble organization `id`, use [Organization signals](/api/core-data/organizations/organization-signals.md) instead.

Use Priority Signals search when you want the AI-generated digest items from your Priority Signals feed, filtered by the signal, organization, person, or job post IDs attached to their source signals.

## Search signals

Search by any combination of signal IDs, organization IDs, person IDs, technology slugs, job function names, priorities, and saved organization list IDs. The request body may be omitted; when present, all filter fields are optional. Filters are combined with AND; values inside each filter array are combined with OR.

```bash
curl https://api.sumble.com/v9/signals \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "signal_ids": [123],
      "organization_ids": [31],
      "person_ids": [12729201],
      "job_functions": ["Account Executive"],
      "priorities": ["high"],
      "account_list_ids": [4]
    }
  }'
```

To search people-movement signals by job function, omit `technology_slugs` unless the same signals also have matching technology metadata.

To search for signals about specific people, pass their Sumble person IDs in `person_ids`. This matches the `person_id` field returned on person-related signals.

### Recency window

This endpoint returns only signals from the **last 30 days**, regardless of the other filters you apply. This keeps searches fast and focused on current activity.

The only exception is a direct lookup by `signal_ids`: those signals are always returned regardless of age.

### Response

The response contains a `signals` array. Each signal includes `signal_id`, a display-ready `title`, `display_type`, and `date`, plus optional context such as `subtitle`, `type`, `organization_name`, `organization_id`, `person_id`, `matched_technologies`, `location`, `job_function`, `priority`, `explanation`, and `sales_angle`.

For person-movement signals, `subtitle` may include a normalized start-date label such as `Started Jun 2026` or `Starting Jul 2026`.

Job-post signals (technology and product mentions, projects, and first mentions) also include `suggested_contacts`: the top contacts to consider reaching out to at the account, ranked by relevance. It contains a `people` array — each with `person_id`, `name`, `title`, `linkedin_url`, and a relevance `score` from 1 to 10 (higher is a stronger match) — and a `sumble_url` linking to all matching people for the job post.

Each signal also includes `account_status`: the CRM relationship between the signal's organization and your account (`customer`, `prospect`, or `not_in_crm`). Only populated when your account has a linked CRM seat (Salesforce or HubSpot); omitted otherwise.

### Credit cost

1 credit per signal returned. Searches with no returned signals do not consume credits.

## Search signals

> Signals are sales-relevant events such as champion job changes, recent hires and promotions, technology and product mentions, projects and initiatives, and technology and job-function trends. Job-post signals (technology and product mentions, projects, and first mentions) also include \`suggested\_contacts\`: the top few people to consider reaching out to at the account, plus a link to view all of them. Each signal also carries \`account\_status\`: the CRM relationship between the signal's organization and the calling account ('customer', 'prospect', or 'not\_in\_crm'). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot).

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SearchSignalsRequest":{"properties":{"filter":{"$ref":"#/components/schemas/SearchSignalsFilter","description":"Filter criteria for signals search."}},"additionalProperties":false,"type":"object","title":"SearchSignalsRequest"},"SearchSignalsFilter":{"properties":{"organization_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Organization Ids","description":"Organization IDs to filter signals by."},"person_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Person Ids","description":"Sumble person IDs to filter signals by."},"signal_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Signal Ids","description":"Signal IDs to filter signals by."},"technology_slugs":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Technology Slugs","description":"Canonical technology slugs to filter signals by, such as `kubernetes` or `salesforce`."},"job_functions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Job Functions","description":"Job function names to filter signals by, such as `Engineering` or `Sales`."},"priorities":{"anyOf":[{"items":{"type":"string","enum":["high","medium","low"]},"type":"array"},{"type":"null"}],"title":"Priorities","description":"Priorities to filter signals by. Matches the `priority` field returned on each signal."},"account_list_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Account List Ids","description":"Account list IDs to filter signals to accounts in those lists."}},"additionalProperties":false,"type":"object","title":"SearchSignalsFilter"},"SignalsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"signals":{"items":{"$ref":"#/components/schemas/Signal"},"type":"array","title":"Signals"}},"type":"object","required":["id","credits_used","credits_remaining","signals"],"title":"SignalsResponse"},"Signal":{"properties":{"signal_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Signal Id"},"title":{"type":"string","title":"Title"},"subtitle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subtitle"},"explanation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Explanation"},"sales_angle":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sales Angle"},"date":{"type":"string","format":"date-time","title":"Date"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"},"display_type":{"type":"string","title":"Display Type"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"matched_technologies":{"anyOf":[{"items":{"$ref":"#/components/schemas/SignalTechnology"},"type":"array"},{"type":"null"}],"title":"Matched Technologies"},"organization_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Name"},"organization_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Organization Id"},"job_post_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Job Post Id"},"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"job_function":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Function"},"priority":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority"},"suggested_contacts":{"anyOf":[{"$ref":"#/components/schemas/SuggestedContacts"},{"type":"null"}]},"account_status":{"anyOf":[{"type":"string","enum":["customer","prospect","not_in_crm"]},{"type":"null"}],"title":"Account Status","description":"CRM relationship between the signal's organization and the calling account: 'customer' (a customer account in the calling account's CRM), 'prospect' (tracked in CRM but not a customer), or 'not_in_crm' (no CRM record). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot); omitted otherwise, even when requested."}},"type":"object","required":["title","date","display_type"],"title":"Signal"},"SignalTechnology":{"properties":{"name":{"type":"string","title":"Name"},"slug":{"type":"string","title":"Slug"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"}},"type":"object","required":["name","slug"],"title":"SignalTechnology"},"SuggestedContacts":{"properties":{"people":{"items":{"$ref":"#/components/schemas/SuggestedContact"},"type":"array","title":"People"},"sumble_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sumble Url"}},"type":"object","required":["people"],"title":"SuggestedContacts"},"SuggestedContact":{"properties":{"person_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Person Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"linkedin_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin Url"},"score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Score"}},"type":"object","title":"SuggestedContact"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals":{"post":{"tags":["signals"],"summary":"Search signals","description":"Signals are sales-relevant events such as champion job changes, recent hires and promotions, technology and product mentions, projects and initiatives, and technology and job-function trends. Job-post signals (technology and product mentions, projects, and first mentions) also include `suggested_contacts`: the top few people to consider reaching out to at the account, plus a link to view all of them. Each signal also carries `account_status`: the CRM relationship between the signal's organization and the calling account ('customer', 'prospect', or 'not_in_crm'). Only populated when the calling account has a linked CRM seat (Salesforce or HubSpot).","operationId":"search_signals__api_version__signals_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchSignalsRequest"}}}},"responses":{"200":{"description":"Signals matching the requested filters. Charged one credit per signal returned. Job-post signals also carry `suggested_contacts` with the top contacts to consider and a link to view all.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Search Priority Signals

Search your Priority Signals digest items by any combination of signal IDs, organization IDs, person IDs, job post IDs, and your relevance feedback. The request body may be omitted; when present, all filter fields are optional. Filters are combined with AND; values inside each filter array are combined with OR.

Priority Signals are AI-generated summaries of the highest-priority signals in your account feed. Each result includes the digest item `id`, headline and content, a URL to view the digest in Sumble, source `signal_ids`, searchable `organization_ids`, `person_ids`, and `job_post_ids` derived from the source signals, and your relevance feedback (`is_relevant`).

```bash
curl https://api.sumble.com/v9/signals/priority \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "filter": {
      "signal_ids": [123],
      "organization_ids": [31],
      "person_ids": [12729201],
      "job_post_ids": [789],
      "is_relevant": true
    }
  }'
```

The `is_relevant` filter accepts `true` (only signals you marked relevant) or `false` (only signals you marked not relevant). Omit it to return priority signals regardless of feedback — omitting it does **not** match only unreviewed (no-feedback) signals.

### Response

The response contains a `priority_signals` array. Each priority signal includes `id`, `url`, `signal_ids`, `headline`, `content`, `date`, `organization_ids`, `person_ids`, `job_post_ids`, and `is_relevant` (`true`, `false`, or `null` when you haven't given feedback). The `date` is returned as `YYYY-MM-DD`.

### Credit cost

1 credit per priority signal returned. Searches with no returned priority signals do not consume credits.

## Search priority signals

> Priority signals are AI-generated digest items summarizing the most important signals in a user's account feed. They optionally can be searched by signal, organization, person, or job post IDs attached to their source signals. Returns the most recent 20 priority signals based on the specified filters, or omit filters to simply return the latest.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"SearchPrioritySignalsRequest":{"properties":{"filter":{"$ref":"#/components/schemas/SearchPrioritySignalsFilter","description":"Filter criteria for priority signals search."}},"additionalProperties":false,"type":"object","title":"SearchPrioritySignalsRequest"},"SearchPrioritySignalsFilter":{"properties":{"organization_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Organization Ids","description":"Organization IDs to filter priority signals by."},"person_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Person Ids","description":"Sumble person IDs to filter priority signals by."},"signal_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Signal Ids","description":"Signal IDs to filter priority signals by."},"job_post_ids":{"anyOf":[{"items":{"type":"integer","exclusiveMinimum":0},"type":"array"},{"type":"null"}],"title":"Job Post Ids","description":"Job post IDs to filter priority signals by."},"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant","description":"Filter by your relevance feedback: true for priority signals you marked relevant, false for ones you marked not relevant. Omit to return priority signals regardless of feedback -- this does not match only unreviewed (null-feedback) signals."}},"additionalProperties":false,"type":"object","title":"SearchPrioritySignalsFilter"},"PrioritySignalsResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"credits_used":{"type":"integer","title":"Credits Used"},"credits_remaining":{"type":"integer","title":"Credits Remaining"},"priority_signals":{"items":{"$ref":"#/components/schemas/PrioritySignal"},"type":"array","title":"Priority Signals"}},"type":"object","required":["id","credits_used","credits_remaining","priority_signals"],"title":"PrioritySignalsResponse"},"PrioritySignal":{"properties":{"id":{"type":"integer","title":"Id"},"url":{"type":"string","title":"Url"},"headline":{"type":"string","title":"Headline"},"content":{"type":"string","title":"Content"},"date":{"type":"string","format":"date","title":"Date"},"signal_ids":{"items":{"type":"integer"},"type":"array","title":"Signal Ids"},"organization_ids":{"items":{"type":"integer"},"type":"array","title":"Organization Ids"},"person_ids":{"items":{"type":"integer"},"type":"array","title":"Person Ids"},"job_post_ids":{"items":{"type":"integer"},"type":"array","title":"Job Post Ids"},"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant","description":"Your relevance feedback on this priority signal: true (relevant), false (not relevant), or null (no feedback given). Update it with the Update Priority Signal Relevance endpoint."}},"type":"object","required":["id","url","headline","content","date"],"title":"PrioritySignal"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals/priority":{"post":{"tags":["signals"],"summary":"Search priority signals","description":"Priority signals are AI-generated digest items summarizing the most important signals in a user's account feed. They optionally can be searched by signal, organization, person, or job post IDs attached to their source signals. Returns the most recent 20 priority signals based on the specified filters, or omit filters to simply return the latest.","operationId":"search_priority_signals__api_version__signals_priority_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPrioritySignalsRequest"}}}},"responses":{"200":{"description":"Priority signals matching the requested filters. Charged one credit per priority signal returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrioritySignalsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Update Priority Signal Relevance

Mark a priority signal (identified by its `id` from Search Priority Signals) as relevant or not relevant, or clear previously-set feedback. This mirrors the relevant / not relevant feedback available in the web app, and the feedback is weighed when generating your future digests.

```bash
curl https://api.sumble.com/v9/signals/priority/88/relevance \
  --request POST \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "is_relevant": true }'
```

Pass `"is_relevant": true` (relevant), `false` (not relevant), or `null` to clear previously-set feedback.

### Response

Returns the updated `id` and `is_relevant`.

### Credit cost

Free — this endpoint does not consume credits.

## Update priority signal relevance

> Mark a priority signal (identified by its \`id\` from Search Priority Signals) as relevant or not relevant, or clear previously-set feedback by passing \`is\_relevant: null\`. Mirrors the relevant / not relevant feedback available in the web app. Free -- does not consume credits.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"UpdatePrioritySignalRelevanceRequest":{"properties":{"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant","description":"Whether this priority signal is relevant (true) or not relevant (false). Pass null to clear previously-set feedback."}},"additionalProperties":false,"type":"object","required":["is_relevant"],"title":"UpdatePrioritySignalRelevanceRequest"},"PrioritySignalRelevanceResponse":{"properties":{"id":{"type":"integer","title":"Id"},"is_relevant":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Relevant"}},"type":"object","required":["id"],"title":"PrioritySignalRelevanceResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/signals/priority/{item_id}/relevance":{"post":{"tags":["signals"],"summary":"Update priority signal relevance","description":"Mark a priority signal (identified by its `id` from Search Priority Signals) as relevant or not relevant, or clear previously-set feedback by passing `is_relevant: null`. Mirrors the relevant / not relevant feedback available in the web app. Free -- does not consume credits.","operationId":"update_priority_signal_relevance__api_version__signals_priority__item_id__relevance_post","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"integer","title":"Item Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePrioritySignalRelevanceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrioritySignalRelevanceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```