> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datamagnet.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Person Engagement Signal

> Monitor LinkedIn posts and mentions from specific people and surface qualified leads from the audience that likes, comments, or shares them.

# Person Engagement Signal

The `person_engagement` signal monitors LinkedIn for posts and/or mentions from specific people, extracts the users who liked or commented on that content, filters them against your Ideal Customer Profile (ICP), and scores each lead 1–3 based on fit and intent.

Use this signal to capture your competitors' audiences, track who engages with your champions, or monitor influencers in your market.

> [!NOTE]
>
> You can create **multiple** `person_engagement` signals — each targeting a different set of people or ICP. Each signal is identified by a `signal_id` returned on creation.

***

## Create a person engagement signal

### Request

**signal\_type** `string` *required*

Must be `"person_engagement"`.

**profile\_urls** `array` *required*

A list of LinkedIn profile URLs for the people to monitor. The system fetches each profile and extracts the LinkedIn `member_id` automatically. URLs that cannot be resolved are returned in `unresolved_profile_urls` and skipped.

```json theme={null}
[
  "https://www.linkedin.com/in/satyanadella/",
  "https://www.linkedin.com/in/williamhgates/"
]
```

> [!NOTE]
>
> Each URL must point to a valid public LinkedIn profile. The resolved full name and member\_id are included in the response. Unresolvable URLs are reported but do not fail the request — as long as at least one URL resolves.

**tracking\_mode** `string`

What type of content to monitor for each person.

| Value | Monitors |
| - | - |
| `"posts"` | Posts published by the person |
| `"mentions"` | Posts where the person is mentioned |
| `"both"` | Both posts and mentions (default) |

**icp** `object`

Ideal Customer Profile filter. If omitted, every engaging lead passes through unfiltered. See the [ICP Filter Reference](#icp-filter-reference) section below.

**date\_posted** `string`

Only surface leads who engaged with content published within this window.

Valid values: `"past-24h"` · `"past-week"` · `"past-month"`

**additional\_emails** `array`

Extra email addresses to receive the lead digest. Your registered account email is always included.

**webhook\_url** `string`

URL to receive qualified leads via POST after each run. See [Webhooks](https://docs.datamagnet.co/api-reference/webhooks.md).

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json Response theme={null}
{
  "message": {
    "signal_id": "b2d4f6a8-1c3e-4g7h-9i0j-k1l2m3n4o5p6",
    "signal_type": "person_engagement",
    "status": "active",
    "person_groups": [
      { "member_id": "ACoAABcd1234", "label": "Satya Nadella" },
      { "member_id": "ACoAAEfgh5678", "label": "Bill Gates" }
    ],
    "unresolved_profile_urls": ["https://www.linkedin.com/in/private-profile/"],
    "tracking_mode": "both",
    "icp": {
      "job_titles": ["VP Sales", "Head of Revenue"],
      "seniority_levels": ["vp", "c_level", "director"],
      "locations": ["United States", "United Kingdom"]
    },
    "email_recipients": ["user@example.com"],
    "webhook_url": "https://yourapp.com/webhooks/signals"
  }
}
```

**signal\_id** `string`

Unique identifier for this signal. **Save this** — required for update and delete operations.

**signal\_type** `string`

Always `"person_engagement"`.

**status** `string`

`"active"` after creation.

**person\_groups** `array`

The resolved people — one entry per successfully fetched profile, each with the LinkedIn `member_id` and the person's full name as the label.

**unresolved\_profile\_urls** `array`

Only present if one or more `profile_urls` could not be resolved. These profiles are not being monitored. The profile may be private, deleted, or the URL may be incorrect.

**tracking\_mode** `string`

The tracking mode in effect: `"posts"`, `"mentions"`, or `"both"`.

**icp** `object`

The ICP configuration, if provided.

***

## ICP filter reference

All fields are optional. If no ICP is provided, every lead passes with a score of 1.0.

### Hard filters — reject leads that don't match

**locations** `array`

Accepted location strings (country names, cities, or regions). A lead passes if **any** value appears in their LinkedIn location.

```json theme={null}
["United States", "Canada", "London"]
```

**exclude\_titles** `array`

Job titles to exclude. Seniority-aware — `"Intern"` excludes `"Marketing Intern"` but not `"VP Sales"`.

```json theme={null}
["Intern", "Student", "Freelancer"]
```

**mandatory\_keywords** `array`

At least one keyword must appear in the lead's profile text.

```json theme={null}
["sales", "revenue", "B2B"]
```

**job\_titles** `array`

Target job titles. Matching is seniority- and function-aware. Leads with confidence below 0.6 are hard-rejected.

```json theme={null}
["VP Sales", "Chief Revenue Officer", "Head of Revenue"]
```

**seniority\_levels** `array`

Restrict to specific seniority bands. Leads with unclassified seniority (`"unknown"`) always pass.

Valid values: `"intern"` `"entry"` `"ic"` `"manager"` `"director"` `"vp"` `"c_level"` `"founder"` `"unknown"`

```json theme={null}
["vp", "c_level", "director", "founder"]
```

### Soft filters — affect score but don't reject

**industries** `array`

Target company industries. Uses semantic matching. Non-matches lower the ICP score rather than hard-rejecting.

```json theme={null}
["SaaS", "B2B Software", "Fintech"]
```

**company\_size** `array`

Target LinkedIn company size bands. Non-matches lower the ICP score. Must match LinkedIn's exact size band strings:

`""` · `"2 - 10"` · `"11 - 50"` · `"51 - 200"` · `"201 - 500"` · `"501 - 1000"` · `"1001 - 5000"` · `"5001 - 10000"` · `"10001+"`

```json theme={null}
["51 - 200", "201 - 500", "501 - 1000"]
```

**negative\_keywords** `array`

Keywords that reduce or eliminate a lead's score if found in their profile text.

```json theme={null}
["recruiting", "hiring manager", "talent acquisition"]
```

***

## Lead scoring

Each lead that passes the hard filters is scored on two dimensions:

**ICP Score (0.0–1.0)** — average of all soft-filter scores (`industries`, `company_size`, `negative_keywords`). Leads with no ICP configured receive 1.0.

**Signal Score** — based on:

* Engagement type: comment = 1.0, like = 0.7
* Recency: decays linearly over 14 days

**Lead Score (1–3)** — `composite = 0.5 × icp_score + 0.5 × signal_score`

| Score | Threshold | Meaning |
| - | - | - |
| 3 | ≥ 0.75 | High-fit, high-intent |
| 2 | ≥ 0.50 | Good fit |
| 1 | \< 0.50 | Weak signal |

Leads are delivered via email digest and/or webhook after each daily run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.