Predictive Signals: who in your audience is in market

Base URL: https://api.delivr.ai
Version: v1
Authentication: Organization API key. Send X-Api-Key: <dlvr_...> and X-Api-Secret: <secret> on every request (both required). Create the key + secret in the dashboard at https://app.delivr.ai/{org_id}/settings/api-keys.

Once you have an intents audience, Predictive Signals answers the next question: which of its members are showing buying intent right now, which companies they roll up to, and whether that intent is accelerating or fading.

See the Predictive Signals reference for the full request and response schemas.

The audience calls

All three take the audience's numeric id in the path. Per-person lookups are covered under "Trends for one person" below.

In market and momentum

A member counts as in market when they were active on 3 or more of the last 14 days on the audience's defining topics, at medium or high score. This is computed daily after 13:40 UTC over the trailing 14-day window ending on the document's day.

Every in-market member is also bucketed into a single best momentum tier, checked in this order:

1. new: first seen active on a defining topic within the window.
2. rising: this week's activity is at least 1.5x the prior week's.
3. steady: roughly flat week over week.
4. cooling: this week's activity is at most half the prior week's.

A member is counted once, under the highest tier that applies.

Reading the overview

GET /api/v1/signals/audiences/{id}?project_id=YOUR_PROJECT_ID

{
  "audience_id": "10482",
  "view": "intents",
  "status": "ready",
  "signals": {
    "day": "20260921",
    "members": 48213,
    "with_intent": 9104,
    "in_market": 2211,
    "momentum": { "new": 340, "rising": 588, "steady": 1102, "cooling": 181, "unknown": 0 },
    "top_companies": [ { "...": "..." } ]
  }
}

status is one of:

• ready: check view before reading signals. When view is intents, signals is present. When view is profile, signals is null; use the topics call instead.
• preparing: the audience has no membership index yet and one has been started; ask again after the next indexing run (hourly, except 03:00-09:00 UTC).
• unavailable: the audience can't have signals right now: a company audience, a paused or failed intents audience, or signals not enabled in this environment. reason says which and what to do (for example, resume or refresh the audience).

Trend, not just a snapshot

GET /api/v1/signals/audiences/{id}/history?project_id=YOUR_PROJECT_ID&range=90d

Returns the same daily counts across the requested window, ending on the audience's latest signals day. range accepts 30d, 90d (default), 180d, or 365d; anything else is a 400.

Unlike the overview, this call never starts preparing the audience: an audience with no history yet answers 200 with days: []. To start preparation, call the overview endpoint above.

Trends for one person

The audience calls above answer questions about a group. To ask about a single person, look them up by hem or email. No audience is needed.

POST /api/v1/signals/people/lookup?project_id=YOUR_PROJECT_ID

{ "id": "lead-1042", "email": "[email protected]", "min_score": "medium" }

{
  "response": {
    "id": "lead-1042",
    "matched": true,
    "matched_on": "email",
    "topics": [
      {
        "topic_id": "crm_software",
        "topic_name": "CRM Software",
        "score": "high",
        "perc_score": 91,
        "intent_trend": "rising",
        "active_days_14d": 6,
        "first_seen": "2026-09-23",
        "last_seen": "2026-10-05"
      }
    ]
  },
  "as_of": "2026-10-05"
}

• Fields. hem (lowercase SHA-256 of the email) or email; a valid hem wins if both are sent. Optional: id (echoed back), topic_ids (keep only these topics), min_score (high or medium, default medium), dry_run.
• Topics. Only high and medium topics that carry a trend are returned. intent_trend is new, rising, steady, or cooling, as for momentum above, but per person and per topic.
• matched. True when at least one trend topic came back after filtering. A person who has opted out looks exactly like a person we do not hold: matched: false, topics: [].
• Batch. POST /api/v1/signals/people/batch takes items (1 to 1,000, each with id, hem, or email) plus the same topic_ids, min_score, and dry_run. It returns {"response": {"results": [...], "matched_count": N}, "as_of": "..."} with results in request order.
• Errors. 400 for min_score: low (low topics carry no trend), linkedin_url, resolve_person, an item with no hem or email, or a batch outside 1 to 1,000. 402 when the spend gate refuses the call. 403 for anything but an API key. 429 when the Platform Cap would be exceeded. 503 when the lookups are not enabled or the data is unavailable; it is retryable and nothing is billed.
• Test keys. A test API key returns a fixed sample person with the header X-Delivr-Mode: test and is never billed. A hem of 64 zeros returns matched: false.

These two calls are for API keys only, and the project comes from X-Project-Id or ?project_id=.

Billing

Calls from the dashboard are never metered. An API-key caller is metered as Predictive Signals:

• One unit per company row returned in the overview's top_companies.
• One unit per result row returned by topics.
• The overview and topics bill the same answer only once per audience per day, no matter how many times it is fetched.
• One unit per history call that returns at least one day. Repeating the call bills again, and a call with days: [] is free.
• One unit per distinct person with at least one trend topic returned by people/lookup or people/batch, counted after topic_ids and min_score are applied. A person with no trend topic, or one filtered out, costs nothing, and a hem repeated in a batch bills once.

Add "dry_run": true to a people call to get records_to_charge back with no topics and no charge.