# Authentication
Source: https://docs.datamagnet.co/api-reference/authentication

Authenticate Datamagnet API requests with bearer tokens. Learn how to generate API keys, attach them to requests, and rotate credentials safely.

# Authentication

You need to authenticate your requests to access any of the endpoints in the Datamagnet API. This guide explains how authentication works. Datamagnet uses bearer tokens to authenticate your API requests.

## Authentication with bearer token

The recommended way to authenticate with the Datamagnet API is by using OAuth2. When you establish a connection using OAuth2, you need your access token — you can find it in the [Datamagnet dashboard → API Keys](https://datamagnet.co/app/api-keys). Here's how to add the token to the request header using cURL:

```bash Example request with bearer token theme={null}
curl https://api.datamagnet.co/api/v1/person \
  -H "Authorization: Bearer {token}"
```

Always keep your token safe and reset it if you suspect it has been compromised.


# Company Profile
Source: https://docs.datamagnet.co/api-reference/endpoints/company

POST https://api.datamagnet.co/api/v1/company
Fetch structured data for a LinkedIn company profile including name, industry, headcount, headquarters, specialties, and recent updates.

# Company

**Cost:** `1` credit / successful request. (Extra charges might be incurred if premium optional parameters are used. Please read the description of the parameters that you intend to use)

The `company_insights` flag costs an additional **10 credits**, charged only when the insights request succeeds. The `get_funding_rounds` flag costs an additional **5 credits**, charged only when the funding rounds request succeeds.

Get structured data of a Company Profile.

## Company profile endpoint

This endpoint allows you to get structured data of a LinkedIn Company Profile.

### Required attributes

**url** `string` *required*

The LinkedIn URL of the company.

### Optional attributes

**use\_cache** `string`

Alters the caching behavior.

* `if-present` - The default behavior. Fetches profile from cache regardless of age of profile. If the profile is not available in cache, the API fetches it live.
* `if-recent` - API will make a best effort to return a fresh profile no older than 29 days.
* `never` - Do not ever read profile from cache.

**lang** `string`

The language in which you need your response.

**company\_insights** `boolean`

Appends LinkedIn-native company insights (headcount trends, hiring trends, notable alumni, job openings by function, and median employee tenure) to `insights`. `false` by default.

Costs an additional `10` credit, subject to data availability, on top of the base endpoint cost.

**get\_funding\_rounds** `boolean`

Looks up the company's funding round history (using the `website` from the company profile) and appends it to `funding_rounds`. `false` by default.

Costs an additional `5` credits, subject to data availability, on top of the base endpoint cost. Same data as the standalone [Funding Rounds](/api-reference/endpoints/funding-rounds) endpoint.

### Response

```json Response theme={null}
{
  "message": {
    "company_id": "1441",
    "company_name": "Google",
    "universal_name_id": "google",
    "formatted_url": "https://www.linkedin.com/company/google",
    "url": "https://www.linkedin.com/company/google",
    "company_type": "Public Company",
    "company_size": "10,001+ employees",
    "employee_count": "327,095",
    "description": "A problem isn't truly solved until it's solved for all...",
    "info": "Google | 39,995,212 followers on LinkedIn...",
    "tagline": null,
    "industry": "Software Development",
    "about_industry": "Software Development",
    "headquarters": "Mountain View, CA",
    "location": "Mountain View, CA",
    "country_code": "US",
    "hq_address": {
      "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043, US",
      "city_state": "Mountain View, CA 94043, US",
      "is_primary": true,
      "map_url": "https://www.bing.com/maps?where=...",
      "street_address": "1600 Amphitheatre Parkway"
    },
    "all_locations": [
      "1600 Amphitheatre Parkway, Mountain View, CA 94043, US",
      "111 8th Ave, New York, NY 10011, US"
    ],
    "locations": [
      {
        "address": "1600 Amphitheatre Parkway, Mountain View, CA 94043, US",
        "city_state": "Mountain View, CA 94043, US",
        "is_primary": true,
        "map_url": "https://www.bing.com/maps?where=...",
        "street_address": "1600 Amphitheatre Parkway"
      }
    ],
    "get_directions_url": [
      {
        "directions_url": "https://www.bing.com/maps?where=..."
      }
    ],
    "founded_year": "1998",
    "followers": "39,995,212",
    "website": "https://goo.gle/3DLEokh",
    "profile_pic_url": "https://media.licdn.com/dms/image/...",
    "background_cover_image_url": "https://media.licdn.com/dms/image/...",
    "specialties": [
      "search",
      "ads",
      "mobile",
      "android",
      "online video"
    ],
    "additional_information": "Google jobs 127,126 open jobs...",
    "crunchbase_url": "https://www.crunchbase.com/organization/google...",
    "stock_info": null,
    "funding": {
      "crunchbase_url": "https://www.crunchbase.com/organization/google...",
      "investors": [
        {
          "logo_url": "https://media.licdn.com/dms/image/...",
          "name": "Kleiner Perkins",
          "url": "https://www.crunchbase.com/organization/..."
        }
      ],
      "last_round": {
        "amount": "US$ 25.0M",
        "date": "Wed, 07 Jul 1999 00:00:00 GMT",
        "type": "Series unknown"
      },
      "total_rounds": 3
    },
    "investors": [
      {
        "logo_url": "https://media.licdn.com/dms/image/...",
        "name": "Kleiner Perkins",
        "url": "https://www.crunchbase.com/organization/..."
      }
    ],
    "jobs": [
      {
        "open_jobs_count": 127126,
        "title": "Google jobs",
        "url": "https://www.linkedin.com/jobs/google-jobs..."
      }
    ],
    "employees": [
      {
        "image_url": "https://media.licdn.com/dms/image/...",
        "name": "Linus Upson",
        "profile_url": "https://www.linkedin.com/in/linusupson?trk=org-employees"
      }
    ],
    "affiliated_pages": [
      {
        "category": "Technology, Information and Internet",
        "location": "Mountain View, CA",
        "logo_url": "https://media.licdn.com/dms/image/...",
        "name": "Google for Developers",
        "url": "https://www.linkedin.com/showcase/googledevelopers/..."
      }
    ],
    "similar_pages": [
      {
        "industry": "Software Development",
        "location": "Redmond, Washington",
        "logo_url": "https://media.licdn.com/dms/image/...",
        "name": "Microsoft",
        "url": "https://www.linkedin.com/company/microsoft..."
      }
    ],
    "update_data": [
      {
        "comments": "48",
        "content": "This week, we expanded the Gemini 3 model family...",
        "posted_time": "Sat, 20 Dec 2025 16:22:15 GMT",
        "reaction_types": ["LIKE", "PRAISE", "EMPATHY"],
        "reactions": "624"
      }
    ],
    "input": "https://www.linkedin.com/company/google",
    "extracted_contacts": {
      "emails": [],
      "personal_emails": [],
      "professional_emails": [],
      "phone_numbers": []
    }
  },
  "credit_used": 1
}
```

```json Not found theme={null}
{
  "error": "Company does not exist.",
  "retryable": false,
  "credit_used": 1
}
```

```json Could not fetch theme={null}
{
  "error": "Could not fetch the page. Try again after some time",
  "retryable": true,
  "credit_used": 0
}
```

### Not found and failed lookups

Both answer HTTP `200` with an `error` and a `retryable` flag instead of `message`:

* `retryable: false`: LinkedIn has no company page at this URL (a removed page, or a slug that was never claimed). The lookup ran, so it costs `1` credit. Repeating it gives the same answer.
* `retryable: true`: we could not get an answer in time. Nothing is charged; retry later.

Fields a company page does not show (a founding year, a website, a headquarters) are `null`. Small or placeholder pages often leave several of them out.

## The company model

This contains the structured data of a company's LinkedIn profile.

### Properties

#### Basic information

**company\_id** `string`

Unique LinkedIn identifier for the company.

**company\_name** `string`

Company name.

**universal\_name\_id** `string`

Universal LinkedIn identifier (vanity URL).

**formatted\_url** `string`

Formatted LinkedIn company page URL.

**url** `string`

LinkedIn company page URL.

**company\_type** `string`

Type of company (e.g., "Public Company", "Private Company", "Partnership").

**company\_size** `string`

Employee headcount range (e.g., "10,001+ employees").

**employee\_count** `string`

Number of employees on LinkedIn, as a string with thousands separators (e.g. `"4,040"`). `null` when the page does not show it.

**tagline** `string`

Company tagline or slogan.

#### Company description

**description** `string`

Detailed company description.

**info** `string`

Additional information about the company.

**additional\_information** `string`

Extended information including job listings and other details.

#### Industry and specialties

**industry** `string`

Primary industry of the company.

**about\_industry** `string`

Detailed industry classification.

**specialties** `array`

List of company specialties and focus areas.

#### Location information

**headquarters** `string`

Headquarters location (city, state/country).

**location** `string`

Primary geographic location.

**country\_code** `string`

ISO country code (e.g., "US", "UK").

**hq\_address** `object`

Detailed headquarters address.

**HQ Address object**

**address** `string`

Full address string.

**street\_address** `string`

Street address.

**city\_state** `string`

City, state, and postal code.

**is\_primary** `boolean`

Whether this is the primary location.

**map\_url** `string`

Bing Maps URL for directions.

**all\_locations** `array`

List of all company locations (addresses as strings).

**locations** `array`

Detailed list of all company locations.

**Location object**

**address** `string`

Full address.

**street\_address** `string`

Street address.

**city\_state** `string`

City and state information.

**is\_primary** `boolean`

Primary location flag.

**map\_url** `string`

Map URL for this location.

**get\_directions\_url** `array`

List of map/directions URLs for all locations.

**Directions object**

**directions\_url** `string`

URL to get directions.

#### Company statistics

**founded\_year** `string`

Year the company was founded. `null` when the page does not list one.

**followers** `string`

Number of LinkedIn followers.

#### Online presence

**website** `string`

Company website URL.

**profile\_pic\_url** `string`

Company logo URL.

**background\_cover\_image\_url** `string`

Company cover/banner image URL.

**crunchbase\_url** `string`

The funding-profile link shown on the company's LinkedIn page. When the page shows none and `get_funding_rounds` is `true`, this is filled from `funding_rounds.crunchbase_url` (unless `funding_rounds.name_verified` is `false`).

#### Funding information

**stock\_info** `object`

Stock market information (if publicly traded).

**funding** `object`

Funding information shown on the company's LinkedIn page.

**Funding object**

**crunchbase\_url** `string`

Funding-profile link.

**total\_rounds** `number`

Total funding rounds.

**last\_round** `object`

Details of most recent funding round.

**Last round object**

**amount** `string`

Funding amount.

**date** `string`

Date of funding round.

**type** `string`

Type of funding round.

**investors** `array`

List of investors.

**Investor object**

**name** `string`

Investor name.

**logo\_url** `string`

Investor logo URL.

**url** `string`

Investor profile URL.

**investors** `array`

Direct list of company investors.

#### Jobs and employees

**jobs** `array`

Available job listings on LinkedIn.

**Job object**

**title** `string`

Job category title.

**open\_jobs\_count** `number`

Number of open positions.

**url** `string`

URL to view jobs.

**employees** `array`

Sample of company employees on LinkedIn.

**Employee object**

**name** `string`

Employee name.

**image\_url** `string`

Employee profile picture URL.

**profile\_url** `string`

Employee LinkedIn profile URL.

#### Related pages

**affiliated\_pages** `array`

List of affiliated company pages (subsidiaries, products, etc.).

**Affiliated page object**

**name** `string`

Page name.

**category** `string`

Industry category.

**location** `string`

Location.

**logo\_url** `string`

Page logo URL.

**url** `string`

LinkedIn page URL.

**similar\_pages** `array`

List of similar companies.

**Similar page object**

**name** `string`

Company name.

**industry** `string`

Company industry.

**location** `string`

Company location.

**logo\_url** `string`

Company logo URL.

**url** `string`

LinkedIn company page URL.

#### Recent updates

**update\_data** `array`

Recent company posts and updates.

**Update object**

**content** `string`

Post content text.

**posted\_time** `string`

When the update was posted.

**reactions** `string`

Total reaction count.

**comments** `string`

Number of comments.

**reaction\_types** `array`

Types of reactions (LIKE, PRAISE, EMPATHY, etc.).

#### Insights

**insights** `object`

Present only when the `company_insights` request flag is `true`. On failure this contains `{ "error": "Unable to fetch this data at this time." }` instead of data, and no extra credit is charged.

**Insights object**

**headcount\_insights** `object`

Total employee count and headcount growth over time.

**Headcount insights object**

**title** `string`

Section title.

**total\_employees** `number`

Current total employee count.

**growth\_periods** `array`

Headcount change over different lookback windows (`month_difference`, `month_difference_str`, `change_percentage`, `change_percentage_str`).

**headcount\_growth** `array`

Monthly headcount history (`employee_count`, `date`).

**function\_headcount\_insights** `object`

Employee distribution and headcount growth broken down by job function.

**Function headcount insights object**

**title** `string`

Section title.

**latest\_headcount\_by\_function** `object`

Most recent snapshot: `headcount_by_function` (array of `percentage`, `urn`, `employee_count`, `name`), `total_count`, `year_month_on`.

**headcount\_growth\_by\_function** `array`

Per-function headcount growth (`urn`, `name`, `growth_periods`).

**hires\_insights** `object`

Hiring trends over time.

**Hires insights object**

**title** `string`

Section title.

**total\_hires** `number`

Total hires tracked.

**hire\_counts** `array`

Monthly hire counts (`all_employee_hire_count`, `year_month_on`).

**alumni\_insights** `object`

Notable people who previously worked at the company.

**Alumni insights object**

**title** `string`

Section title.

**total\_number\_of\_alumni** `number`

Total tracked alumni.

**alumni** `array`

List of alumni (`exited_position`, `exit_year_month_on`, `profile` with `full_name`/`url`/`username`).

**job\_openings\_insights** `object`

Job openings by function and their growth trends.

**Job openings insights object**

**title** `string`

Section title.

**job\_openings\_by\_function** `array`

Snapshots of open roles by function over time (`total_count`, `year_month_on`, `count_by_function`).

**job\_openings\_growth\_all\_functions** `array`

Overall job openings growth (`month_difference`, `month_difference_str`, `change_percentage`, `change_percentage_str`).

**jobs\_openings\_growth\_unselected\_functions** `array`

Job openings growth for functions not individually broken out.

**job\_openings\_growth\_by\_function** `array`

Per-function job openings growth (`urn`, `name`, `growth_periods`).

**median\_employee\_tenure** `number`

Median employee tenure in years.

#### Funding rounds

**funding\_rounds** `object`

Present only when the `get_funding_rounds` request flag is `true`. On failure this contains `{ "error": "Unable to fetch this data at this time." }` instead of data, and no extra credit is charged. See the [Funding Rounds](/api-reference/endpoints/funding-rounds) endpoint for the full field reference.

**Funding rounds object**

**domain** `string`

Company domain that was looked up.

**crunchbase\_url** `string`

Link to the company's public funding profile. `null` if no funding data was found.

**matched\_via** `string`

How the company was found: `domain` or `company_name`.

**name\_verified** `boolean`

Whether the matched company's name lines up with the profile's `company_name`.

**total\_rounds** `integer`

Number of funding rounds returned.

**total\_raised\_usd** `integer`

Total amount raised across all rounds, in USD.

**total\_raised\_formatted** `string`

Human-readable total raised (e.g. `$11.60B`).

**rounds** `array`

List of funding rounds, most recent first.

#### Request echo and contacts

**input** `string`

The LinkedIn URL the profile was collected from.

**extracted\_contacts** `object`

Email addresses and phone numbers the company published on its page (About section, page description, its own posts). LinkedIn has no structured contact field for companies, so this is often empty. No extra credit is charged.

**Contacts object**

**emails** `array`

Every address found: `email`, `type`, `domain`, `sources`.

**personal\_emails** `array`

The subset on consumer mailboxes (Gmail, Outlook and the like).

**professional\_emails** `array`

Every other address.

**phone\_numbers** `array`

Numbers found: `number` (as written), `e164` (normalised, `null` when it cannot be resolved), `raw`, `sources`, and `country_code`, `region`, `line_type`, `is_valid`.


# Company Search DB
Source: https://docs.datamagnet.co/api-reference/endpoints/company-db-search

POST https://api.datamagnet.co/api/v1/company/search/db
Search Datamagnet's own database of company profiles by industry, location, headcount, type, founding year and LinkedIn identity — firmographic filters over previously collected records.

# Company Search DB

**Cost:** `10` credits/search.

Search Datamagnet's internal database of company profiles by firmographics. Like [People Search DB](/api-reference/endpoints/people-db-search), this queries records already collected rather than fetching live, so it returns instantly and doesn't consume collection capacity. Each page returns up to `500` companies.

## Company search DB endpoint

Every list field is OR'd within itself and AND'd across fields — `industries: ["Retail", "Restaurants"]` with `countries: ["US"]` means retail **or** restaurants, in the US.

**At least one filter is required.** A search with none is refused with a `422`, uncharged: there is no useful answer to "return anything" over 38 million companies.

> [!WARNING]
>
> Most of these filters match the stored value **exactly**, not as a substring — that is what lets an index answer them on a table this size. Exact means exact: `company_types: ["Privately Held"]` matches, `["private"]` matches nothing. Where a field has more than one spelling in the data, pass every spelling you want, and see the coverage table at the end for how much of the database each field is filled on.
>
> `industries` is the exception. It is resolved against a known vocabulary before it is matched, so one name finds every spelling of that industry and a shorthand widens rather than matching nothing — `["software"]` becomes the nine industries with "software" in the name. Still exact against the index, just not against your word. See below.

### Industry and type

**industries** `string[]`

Filter by industry. Pass one of the [443 industry names](/api-reference/values/employer-industries) — `Medical Practices`, `Construction`, `Restaurants`, `Retail`, `Real Estate`, `Insurance`, `Software Development`.

**One name finds every spelling of the industry.** Three things used to split one industry across several values here, and all three are now folded: the 2022 LinkedIn rename (`Computer Software` is the legacy spelling of `Software Development`), the casing (`telecommunications` and `Telecommunications` are separate stored values), and the punctuation (`Information Technology & Services` versus `information technology and services`). `Software Development` alone now matches 908,623 companies where it used to match 660,254.

A shorthand of 4+ characters widens to the industries containing it. A word we don't recognise is a `422` with near misses, never an empty result.

Example: `["Software Development"]`

**company\_types** `string[]`

Filter by company type, matched exactly. Values seen in the data: `Privately Held`, `Public Company`, `Nonprofit`, `Self-Owned`, `Self-Employed`, `Partnership`, `Government Agency`, `Educational`.

Example: `["Privately Held", "Public Company"]`

**entity\_types** `string[]`

What kind of LinkedIn page this is: `company`, `school` or `showcase`. Case-insensitive.

Example: `["company"]`

### Location

**countries** `string[]`

Filter by country as an ISO-3166-1 alpha-2 code, not a name — `US`, not `United States`. Case-insensitive.

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

**regions** `string[]`

State, province or other first-level region, matched exactly as stored. Example: `["California", "Texas"]`

**cities** `string[]`

City, matched exactly as stored. Example: `["San Francisco", "Austin"]`

### Size

**min\_employees** `integer`

Minimum employee count. This is the numeric headcount, filled on about 42% of companies — for broader coverage use `size_bands`, which is filled on 98%.

Example: `50`

**max\_employees** `integer`

Maximum employee count. Example: `500`

**size\_bands** `string[]`

Filter by LinkedIn's headcount band, matched exactly as stored: `1 employee`, `2-10 employees`, `11-50 employees`, `51-200 employees`, `201-500 employees`, `501-1,000 employees`, `1,001-5,000 employees`, `5,001-10,000 employees`, `10,001+ employees`.

Older records carry shorter spellings of the same bands (`1-10`, `11-50`) and a few carry `0+ employees`. Pass every spelling you want matched — these are exact comparisons, not ranges.

Example: `["11-50 employees", "51-200 employees"]`

### Age and reach

**founded\_min** `integer`

Founded in or after this year. Example: `2010`

**founded\_max** `integer`

Founded in or before this year.

The founding year is stored as free text, so it is read as the first four digits of the value — `1998-2000 (relocated 2015)` reads as 1998, `2,024` reads as 2024. A company whose stored value holds no year at all never matches either bound.

Example: `2020`

**min\_followers** `integer`

Minimum LinkedIn follower count. Example: `1000`

### Web presence

**has\_website** `boolean`

`true` returns only companies we hold a website for, `false` only those we hold none for. Like the contactability filters on the people search, this describes our records rather than the company.

Example: `true`

### LinkedIn identity

**linkedin\_ids** `string[]`

Filter by numeric LinkedIn company ID. Exact match, and the fastest way to hydrate a list of companies you already know.

Example: `["1035", "1441"]`

**linkedin\_usernames** `string[]`

Filter by LinkedIn universal name — the last path segment of the company URL. Case-insensitive, exact match.

Example: `["stripe", "plaid"]`

### Paging

> [!NOTE]
>
> Results are **not ordered**. Nothing worth sorting by is indexed on a table this size, so a sort would mean collecting every match before returning a page of them. Paging with `limit`/`offset` is therefore best-effort: it walks the result set, but the order it walks in is not guaranteed to be stable between calls.

**limit** `integer` (default: 50)

Maximum number of companies to return per page, from `1` to `500`. A value outside that range is rejected rather than quietly reduced.

**offset** `integer` (default: 0)

Number of results to skip, for pagination.

### Unrecognised fields

A field name this endpoint doesn't know is not applied. The search still runs, and the response carries an `ignored_filters` array naming what was dropped — so a mistyped `industry` (for `industries`) shows up as a named mistake instead of a page of results that looks filtered but isn't.

If **every** filter in the request was unrecognised, the search is refused with a `422` and no credits are charged.

***

## Response

```json Request theme={null}
{
  "industries": ["Software Development"],
  "countries": ["US"],
  "regions": ["California"],
  "size_bands": ["51-200 employees", "201-500 employees"],
  "company_types": ["Privately Held"],
  "founded_min": 2010,
  "min_followers": 1000,
  "has_website": true,
  "limit": 50,
  "offset": 0
}
```

```json Response theme={null}
{
  "message": [
    {
      "id": 84210,
      "linkedin_id": "1035",
      "username": "examplesoft",
      "linkedin_url": "https://www.linkedin.com/company/examplesoft",
      "entity_type": "company",
      "name": "ExampleSoft",
      "industry": "Software Development",
      "headcount_range": "51-200 employees",
      "employee_count": 138,
      "company_type": "Privately Held",
      "founded": "2013",
      "followers": 8421,
      "domain": "https://examplesoft.com",
      "headquarters": "San Francisco, California, United States",
      "hq_city_state": "San Francisco, California",
      "country_code": "US",
      "region": "California",
      "city": "San Francisco",
      "updated_at": "2026-08-02T09:14:55"
    }
  ],
  "credit_used": 10,
  "total": 1
}
```

## The response model

Results never carry the company description, the long-form `info` block or the raw collected payload. Those three are the bulk of the stored record, and a search that returned them would spend its whole budget fetching them. Use [Company](/api-reference/endpoints/company) on a result's `linkedin_url` for the full profile.

**message** `array`

List of matching companies.

**Company object**

**id** `integer`

Internal Datamagnet company ID.

**linkedin\_id** `string`

Numeric LinkedIn company ID.

**username** `string`

LinkedIn universal name (the last segment of the company URL).

**linkedin\_url** `string`

LinkedIn company page URL.

**entity\_type** `string`

`company`, `school` or `showcase`.

**name** `string`

Company name.

**industry** `string`

LinkedIn industry taxonomy string.

**headcount\_range** `string`

LinkedIn headcount band, e.g. `51-200 employees`.

**employee\_count** `integer`

Numeric employee count, when available.

**company\_type** `string`

e.g. `Privately Held`, `Public Company`, `Nonprofit`.

**founded** `string`

Founding year as stored. Free text: usually a year, occasionally a range.

**followers** `integer`

LinkedIn follower count.

**domain** `string`

Company website.

**headquarters** `string`

Full headquarters location string.

**hq\_city\_state** `string`

Headquarters city and region.

**country\_code** `string`

ISO-3166-1 alpha-2 country code.

**region** `string`

State, province or first-level region.

**city** `string`

City.

**updated\_at** `string`

When this record was last refreshed. Every figure above is as old as this timestamp — read it beside `employee_count` and `followers` in particular.

**credit\_used** `integer`

Number of credits used for this request. Example: `10`

**total** `integer`

Number of results returned in this response.

**ignored\_filters** `string[]`

Present only when the request contained field names this endpoint doesn't recognise. Names them, so a typo shows up as a typo rather than as results that look filtered but aren't.

## Field coverage

A filter can only return companies whose record holds that field, so coverage is the real ceiling on any search. Measured across 38.4M companies on 2026-09-22:

| Filter | Field is filled on |
| - | - |
| `size_bands` | 97.8% |
| `countries` | 87.8% |
| `industries` | 85.3% |
| `regions` | 77.3% |
| `cities` | 73.1% |
| `has_website` | 72.0% |
| `min_followers` | 64.2% |
| `company_types` | 43.3% |
| `min_employees` / `max_employees` | 41.8% |
| `founded_min` / `founded_max` | 37.4% |

Combining a well-covered filter with a sparse one narrows twice: `min_employees` with `founded_min` can only return the companies that carry both.

## Errors

| Status | Meaning | What to do |
| - | - | - |
| `400` | The body was not a JSON object, or `limit` was outside `1`–`500`, or `offset` was negative. `message` names the problem. | Fix the request. |
| `422` | The request carried no filters at all, every filter in it was an unrecognised field name, or `industries` named something that is none of the [443](/api-reference/values/employer-industries). `message` lists what is accepted, with near misses for an industry. | Add a filter, or correct the name or value. |
| `504` | The search ran too long to answer. | Narrow it and retry — a country or a size band alongside the industry. |

Nothing is charged on any error.


# Company Posts
Source: https://docs.datamagnet.co/api-reference/endpoints/company-posts

POST https://api.datamagnet.co/api/v1/company/posts
Retrieve posts published on a LinkedIn company page by URL, including text, media, engagement counts, and timestamps for content monitoring.

# Company Posts

**Cost:** `10` credits / successful request.

This endpoint retrieves posts from a LinkedIn company page based on the provided company URL. The response includes details about the company's posts, including text content, attachments, reactions, comments, and more.

## Company posts endpoint

This endpoint allows you to get structured data of posts from a LinkedIn Company Profile.

### Required attributes

**url** `string` *required*

The LinkedIn company URL whose posts you want to retrieve.

### Optional attributes

**type** `string`

Alters the type of posts to be fetched.

* `all` - The default behavior. Fetches all types of posts.
* `articles` - Fetch only articles posted by the company.
* `documents` - Fetch only document posts.

**cursor** `string`

Use this parameter to paginate through results. Use the cursor returned from your previous request.

### Response

```json Response theme={null}
{
  "cursor": "eyJjb3VudCI6MTAwLCJzdGFydCI6MTAwLCJ0b3RhbCI6MzY1...",
  "total": 365,
  "message": [
    {
      "attachments": [
        {
          "subtitle": "Google",
          "title": "Gemini 3 Flash is rolling out now — hear from the Googlers who helped make it",
          "type": "Article",
          "url": "https://www.linkedin.com/pulse/gemini-3-flash...",
          "urn": "urn:li:linkedInArticle:7407901974379008000"
        }
      ],
      "author": {
        "followers": 39995212,
        "logo": "https://media.licdn.com/dms/image/...",
        "name": "Google",
        "public_identifier": "google",
        "type": "Company",
        "url": "https://www.linkedin.com/company/google",
        "urn": "urn:li:fsd_company:1441"
      },
      "comments": 48,
      "created_at": "2025-12-20T16:06:30.020Z",
      "is_repost": false,
      "likes": 624,
      "mentions": [],
      "reactions": [
        { "count": 552, "reaction_type": "LIKE" },
        { "count": 33, "reaction_type": "PRAISE" },
        { "count": 21, "reaction_type": "EMPATHY" }
      ],
      "shared_post": null,
      "shares": 52,
      "text": "This week, we expanded the Gemini 3 model family with the release of Gemini 3 Flash...",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7408175976368472064/",
      "urn": "urn:li:activity:7408175976368472064"
    },
    {
      "attachments": [],
      "author": {
        "background_image": null,
        "first_name": "Kent",
        "followers": null,
        "image_url": "https://media.licdn.com/dms/image/...",
        "last_name": "Walker",
        "occupation": "President, Global Affairs at Google & Alphabet",
        "public_identifier": "kent-walker-5963bb198",
        "type": "Member",
        "url": "https://www.linkedin.com/in/kent-walker-5963bb198",
        "urn": "urn:li:fsd_profile:ACoAAC5VbIIBM7MqyDczwsY_EinOMS5UTJRqITo"
      },
      "comments": 24,
      "created_at": "2025-12-19T19:30:50.350Z",
      "is_repost": true,
      "likes": 295,
      "mentions": [],
      "original_post_urn": "urn:li:ugcPost:7407823617180340224",
      "reactions": [
        { "count": 254, "reaction_type": "LIKE" },
        { "count": 21, "reaction_type": "INTEREST" }
      ],
      "repost_user": {},
      "shared_post": null,
      "shares": 29,
      "text": "As we close out another year, I've been thinking a lot about perceptions of AI...",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7407865012054142977/",
      "urn": "urn:li:activity:7407865012054142977"
    }
  ]
}
```

### How far back posts go

A company page's posts go back about 12 months. Older posts are not available, and the `cursor` is empty once the feed reaches that point.

### Empty and failed responses

* A company page with no posts answers `200` with `"message": []` and no cursor, charged as a normal request.
* A company page that does not exist answers HTTP `404` with `"message": "Company does not exist."` and `"retryable": false`. The lookup ran, so it is charged like a successful request; repeating it gives the same answer.
* When the posts could not be fetched for a temporary reason, the response is HTTP `400` with `"status": "failed"`, a `message` string and a `request_id`. Nothing is charged; retry later.

## The company posts model

### Properties

**cursor** `string`

Pagination token for fetching more posts. Use this in the next request to get the next page. `null` when there are no more posts. A page can hold fewer than 100 posts and still be the last one (posts LinkedIn no longer serves are dropped), so read the end of the feed from `cursor`, not from the page length.

**total** `integer`

How many posts LinkedIn reports for the company's feed. LinkedIn serves roughly the last twelve months of a company's posts, so this can be lower than the number the company has ever published. `null` when the count is not available.

**message** `array`

List of company posts.

**Post object**

#### Post Content

**text** `string`

Text content of the post.

**url** `string`

LinkedIn URL of the post.

**urn** `string`

Unique LinkedIn URN identifier for the post.

**created\_at** `string`

ISO 8601 timestamp when the post was created.

#### Post Type

**is\_repost** `boolean`

Whether this post is a repost/share of another post.

**original\_post\_urn** `string`

URN of the original post (if this is a repost).

**original\_post\_url** `string`

LinkedIn URL of the original post (if this is a repost). A repost is its own post with its own URL, so use this URL, not `url`, to read the original's reactions with [Post Reactions](/api-reference/endpoints/post-reactions).

**repost\_user** `object`

Information about the user who reposted (for company reposts of member content). Often an empty object.

**shared\_post** `object`

The original post, when the company quoted it with commentary of its own. A plain repost has no commentary: the post itself carries the original's content and `shared_post` is `null`. Either way, `original_post_urn` names the original.

#### Post Author

**author** `object`

Details about the post author (company or person).

**Author object - Company**

**name** `string`

Company name.

**type** `string`

Author type ("Company" or "Member").

**url** `string`

LinkedIn company page URL.

**public\_identifier** `string`

Company vanity URL identifier.

**logo** `string`

Company logo URL.

**followers** `number`

Number of company followers.

**urn** `string`

Company URN identifier. Can be an empty string; use `url` or `public_identifier` to identify the author.

**Author object - Member**

**first\_name** `string`

Author's first name (for member posts).

**last\_name** `string`

Author's last name (for member posts).

**occupation** `string`

Author's LinkedIn headline.

**type** `string`

Author type ("Member").

**url** `string`

LinkedIn profile URL.

**public\_identifier** `string`

Profile vanity URL identifier.

**image\_url** `string`

Profile picture URL.

**background\_image** `string`

Profile background image URL.

**followers** `number`

Number of profile followers (may be null).

**urn** `string`

Profile URN identifier.

#### Attachments

**attachments** `array`

List of media attachments (images, videos, articles, documents).

**Attachment object**

**type** `string`

Type of attachment ("Image", "Video", "Document", "Article", etc.).

**url** `string`

URL of the attachment or article.

**title** `string`

Title of the attachment.

**subtitle** `string`

Subtitle or source of the attachment.

**text** `string`

Description or caption text.

**urn** `string`

URN identifier for the attachment.

#### Engagement Metrics

**likes** `number`

Total number of likes/reactions.

**comments** `number`

Number of comments on the post.

**shares** `number`

Number of times the post was shared/reposted.

**reactions** `array`

Breakdown of reactions by type.

**Reaction object**

**count** `number`

Number of this reaction type.

**reaction\_type** `string`

Type of reaction: "LIKE", "PRAISE", "EMPATHY", "INTEREST", "APPRECIATION", "ENTERTAINMENT", "MAYBE", "FUNNY".

#### Mentions

**mentions** `array`

List of @mentioned users or companies in the post.


# Credit Balance
Source: https://docs.datamagnet.co/api-reference/endpoints/credits

GET https://api.datamagnet.co/api/v1/credit-check
Check your current Datamagnet API credit balance to monitor usage and avoid running out of credits during high-volume data collection runs.

# Credit Balance

**Cost:** `0` credit.

Get your current credit(s) balance

## View credit balance endpoint

### Response

```json Response theme={null}
{
  "remaining_credits": 10000,
  "total_credits": 10000,
  "used_credits": 0,
  "api_key": "xxxxxx"
}
```

## The credit model

### Properties

**remaining\_credits** `integer`

The number of credits remaining in the account.

**total\_credits** `integer`

The total number of credits in the account.

**used\_credits** `integer`

The number of credits used in the account.

**api\_key** `string`

API key used in the request.


# Funding Rounds
Source: https://docs.datamagnet.co/api-reference/endpoints/funding-rounds

POST https://api.datamagnet.co/api/v1/company/funding-rounds
Retrieve a company's funding history by domain, with structured data on each round including amount raised, round type, and announcement date.

# Funding Rounds

**Cost:** `5` credits / successful request.

Get a company's funding round history by domain. This same data can also be attached directly to a [Company Profile](/api-reference/endpoints/company) response via the `get_funding_rounds` flag.

## Funding rounds endpoint

This endpoint identifies the company from its domain and returns its funding round history.

### Required attributes

**domain** `string` *required*

Company domain (e.g. `openai.com`). A full website URL also works.

### Optional attributes

**company\_name** `string`

Company name. Providing this improves match accuracy.

### Response

```json Response theme={null}
{
  "message": {
    "domain": "openai.com",
    "crunchbase_url": "https://www.crunchbase.com/organization/openai",
    "company": "OpenAI",
    "matched_via": "domain",
    "name_verified": true,
    "total_rounds": 3,
    "total_raised_usd": 11600000000,
    "total_raised_formatted": "$11.60B",
    "rounds": [
      {
        "round_name": "Corporate Round",
        "round_type": "corporate_round",
        "date": "2023-01-23",
        "amount_usd": 10000000000,
        "amount_formatted": "$10.00B",
        "currency": "USD",
        "company": "OpenAI"
      },
      {
        "round_name": "Secondary Market",
        "round_type": "secondary_market",
        "date": "2019-07-23",
        "amount_usd": 1000000000,
        "amount_formatted": "$1.00B",
        "currency": "USD",
        "company": "OpenAI"
      }
    ]
  },
  "credit_used": 5
}
```

If no funding data is found for the company, `crunchbase_url` is `null` and `rounds` is an empty array — this is still a `200` response, with `credit_used: 0`. A company that is found but has no rounds yet is charged normally.

If the data can't be fetched at this time, the response contains `{ "error": "Unable to fetch this data at this time." }` in `message` with `credit_used: 0`, and no credits are charged.

## The funding rounds model

### Properties

**domain** `string`

Company domain that was looked up.

**crunchbase\_url** `string`

Link to the company's public funding profile. `null` if no funding data was found.

**company** `string`

Company name as recorded in the funding record.

**matched\_via** `string`

How the company was found: `domain` or `company_name`. `null` if no funding data was found.

**name\_verified** `boolean`

Whether the matched company's name lines up with the `company_name` you provided. `null` if `company_name` wasn't provided.

**total\_rounds** `integer`

Number of funding rounds returned.

**total\_raised\_usd** `integer`

Total amount raised across all rounds, in USD.

**total\_raised\_formatted** `string`

Human-readable total raised (e.g. `$11.60B`).

**rounds** `array`

List of funding rounds, most recent first.

**Funding round object**

**round\_name** `string`

Human-readable round name (e.g. "Series A", "Corporate Round").

**round\_type** `string`

Machine-readable investment type (e.g. `series_a`, `corporate_round`).

**date** `string`

Date the round was announced (YYYY-MM-DD).

**amount\_usd** `integer`

Amount raised in this round, converted to USD.

**amount\_formatted** `string`

Human-readable amount raised (e.g. `$1.2M`).

**currency** `string`

Currency of the original investment.

**company** `string`

Name of the funded company.


# ICP Company Search
Source: https://docs.datamagnet.co/api-reference/endpoints/icp-company-search

POST https://api.datamagnet.co/api/v1/people-search/search/company
Find target accounts with ICP filters for industry, headcount, revenue, technology, and location. Uses human-readable values — no IDs required.

# ICP Company Search

**Cost:** `10` credits per page.

Search for companies using Datamagnet's ICP Search. Filter by industry, location, headcount, revenue, technology stack, and more.

> [!TIP]
>
> Use `GET /api/v1/people-search/filters` to see all valid values for any filter. No credits consumed.

## Request body

> [!NOTE]
>
> `keywords` is not supported here — company search ignores free-text queries. Use the structured filters below, or [ICP People Search](/api-reference/endpoints/icp-people-search), which does support `keywords`. Sending it returns `400`.

**page** `integer` (default: 1)

Page number. Minimum value is `1`.

**industry** `string | string[]`

Industry name(s). Over 300 industries supported. See [Filter Reference](/api-reference/endpoints/icp-search-filters#industry).

Example: `"Software Development"`

**location** `string | string[]`

City, region, or country.

Example: `"San Francisco"` or `["San Francisco", "London"]`

**company\_headcount** `string | string[]`

Company size range(s). Valid values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1,000`, `1,001-5,000`, `5,001-10,000`, `10,001+`.

Example: `["501-1,000", "1,001-5,000"]`

**company\_type** `string | string[]`

Company type(s). Valid values: `Public`, `Private`, `Non Profit`, `Educational`, `Government`.

Example: `"Public"`

**technology** `string | string[]`

Technologies used by the company.

Example: `"Salesforce"` or `["Salesforce", "HubSpot"]`

**followers\_count** `string | string[]`

LinkedIn follower count range. Valid values: `1-50`, `51-100`, `101-1000`, `1001-5000`, `5001+`.

Example: `"1001-5000"`

***

## Response

```json Response theme={null}
{
  "success": true,
  "results": [
    {
      "company_id": "15285098",
      "company_name": "Stripe",
      "description": "Stripe is a technology company that builds economic infrastructure for the internet.",
      "industry": "Financial Services",
      "employee_count_range": "1001-5000",
      "employee_count": 4000,
      "company_url": "https://www.linkedin.com/company/stripe/",
      "logo_url": "https://media.licdn.com/dms/image/..."
    }
  ],
  "pagination": {
    "page": 1,
    "total": 134,
    "count": 25,
    "start": 0
  },
  "filters_applied": 3
}
```

## Response fields

**success** `boolean`

`true` on success.

**results** `array`

List of matching companies.

**Company object**

**company\_id** `string`

Internal company identifier.

**company\_name** `string`

Company name.

**description** `string`

Company description (nullable).

**industry** `string`

Industry (nullable).

**employee\_count\_range** `string`

Employee count range string (nullable).

**employee\_count** `integer`

Approximate employee count (nullable).

**company\_url** `string`

LinkedIn company profile URL (nullable).

**logo\_url** `string`

Company logo URL (nullable).

**pagination** `object`

**Pagination object**

**page** `integer`

Current page number.

**total** `integer`

Total results across all pages.

**count** `integer`

Results on this page.

**start** `integer`

Offset of the first result.

**filters\_applied** `integer`

Number of filters applied to this search.


# ICP People Search
Source: https://docs.datamagnet.co/api-reference/endpoints/icp-people-search

POST https://api.datamagnet.co/api/v1/people-search/search
Find decision-makers with ICP filters for job title, seniority, function, company name, LinkedIn URL, company ID, location, and industry.

# ICP People Search

**Cost:** `10` credits per page.

Search for people using Datamagnet's ICP Search. Pass filter values as plain strings — the API handles all resolution internally.

> [!TIP]
>
> Use `GET /api/v1/people-search/filters` to see all valid values for any filter. No credits consumed.

## Request body

**page** `integer` (default: 1)

Page number. Minimum value is `1`.

**keywords** `string`

Free-text query, matched across the whole profile (headline, summary, positions) rather than one attribute. Applied alongside the structured filters, so it narrows them rather than replacing them. Maximum 500 characters.

Example: `"Representative Director"`

**partial** `boolean` (default: false)

What to do when a filter value cannot be resolved (a title LinkedIn's typeahead has no entry for, a company name that matches nothing). By default the search is refused with `422` and nothing is charged. With `true`, the search runs on everything that did resolve: only the refused values are dropped, never a whole field that resolved in part, and each dropped value is listed in `filter_errors`.

A field whose values all fail is dropped entirely, so a `company_name` that matches nothing would search every company. Check `filter_errors` before trusting a partial result.

**job\_title** `string | string[]`

Job title(s) to filter by.

Example: `"CTO"` or `["CTO", "Chief Technology Officer"]`

**company\_name** `string | string[]`

Company name(s). Resolved via Sales Navigator suggest API.

Example: `"Stripe"` or `["Stripe", "Plaid"]`

**company\_linkedin\_urls** `string | string[] | object[]`

LinkedIn company page URL(s). The API scrapes each URL to extract the company's LinkedIn ID and name — no manual lookup needed. Supports include/exclude.

```json theme={null}
"company_linkedin_urls": [
  "https://www.linkedin.com/company/salesforce/",
  { "value": "https://www.linkedin.com/company/competitor/", "exclude": true }
]
```

**company\_ids** `integer | integer[] | object[]`

Raw LinkedIn company numeric ID(s). Builds the filter with the ID directly — no text resolution needed. Must be integers; strings will return a validation error. Supports include/exclude.

```json theme={null}
"company_ids": [1441, { "value": 9876, "exclude": true }]
```

**location** `string | string[]`

City, region, or country.

Example: `"San Francisco"` or `["San Francisco", "New York"]`

**seniority** `string | string[]`

Seniority level(s). See [Filter Reference](/api-reference/endpoints/icp-search-filters#seniority-level) for all valid values.

Example: `["CXO", "Vice President"]`

**company\_headcount** `string | string[]`

Company size range(s). Valid values: `1-10`, `11-50`, `51-200`, `201-500`, `501-1,000`, `1,001-5,000`, `5,001-10,000`, `10,001+`.

Example: `["501-1,000", "1,001-5,000"]`

**industry** `string | string[]`

Industry name(s). Over 300 industries supported. See [Filter Reference](/api-reference/endpoints/icp-search-filters#industry).

Example: `"Software Development"`

**company\_type** `string | string[]`

Company type(s). Valid values: `Public`, `Private`, `Non Profit`, `Educational`, `Government`.

Example: `"Public"`

**function** `string | string[]`

Department/function. Valid values include: `Engineering`, `Marketing`, `Sales`, `Finance`, `Operations`, `Product Management`, and more.

Example: `"Engineering"`

**school** `string | string[]`

University or school name(s).

Example: `"MIT"`

**technology** `string | string[]`

Technologies used by the person's company.

Example: `"Salesforce"`

**years\_in\_position** `string | string[]`

Years in current role. Valid values: `Less than 1 year`, `1 to 2 years`, `3 to 5 years`, `6 to 10 years`, `More than 10 years`.

Example: `"1 to 2 years"`

**recently\_changed\_jobs** `string | boolean`

People who recently started a new position — Sales Navigator's **Changed jobs** spotlight. One value, so a boolean works: send `true`, or the string `"Changed Jobs"`.

`false` is the same as omitting the field — it does not ask for people who have *not* changed jobs. See [Filter Reference](/api-reference/endpoints/icp-search-filters#recently-changed-jobs).

Example: `true`

**posted\_on\_linkedin** `string | boolean`

People who have recently posted on LinkedIn — Sales Navigator's **Posted on LinkedIn** spotlight. One value, so a boolean works: send `true`, or the string `"Posted on LinkedIn"`.

`false` is the same as omitting the field — it does not ask for people who have *not* posted. See [Filter Reference](/api-reference/endpoints/icp-search-filters#posted-on-linkedin).

Example: `true`

**followers\_count** `string | string[]`

LinkedIn follower count range. Valid values: `1-50`, `51-100`, `101-1000`, `1001-5000`, `5001+`.

Example: `"1001-5000"`

**profile\_language** `string | string[]`

Language the profile is written in. Valid values include `English`, `Spanish`, `French`, `German`, and more.

Example: `"English"`

***

## Company filter options

Three ways to filter by company — use whichever fits your data:

| Field | What you provide |
| - | - |
| `company_name` | Company name as a string |
| `company_linkedin_urls` | LinkedIn company page URL(s) |
| `company_ids` | LinkedIn numeric company ID(s) |

> [!NOTE]
>
> All three fields can be combined in the same request.

***

## Include / exclude

Every filter supports negative matching. Wrap a value in an object with `"exclude": true` to exclude it:

```json theme={null}
{
  "company_linkedin_urls": [
    "https://www.linkedin.com/company/salesforce/",
    { "value": "https://www.linkedin.com/company/competitor-co/", "exclude": true }
  ],
  "company_ids": [
    1441,
    { "value": 9876, "exclude": true }
  ],
  "seniority": "CXO"
}
```

***

## Refused values

A value that cannot be resolved refuses that value, not the search as a whole. Unless `partial` is `true`, the response is `422`, costs nothing, and names every refused value, one entry each:

```json theme={null}
{
  "success": false,
  "error": "Some filters could not be applied, so the search was not run.",
  "details": [
    {"field": "job_title", "value": "CSM", "error": "No results found for 'CSM' in 'job_title'. Try a more specific query."},
    {"field": "job_title", "value": "BD Executive", "error": "No results found for 'BD Executive' in 'job_title'. Try a more specific query."},
    {"field": "company_name", "value": "Arzule", "error": "No results found for 'Arzule' in 'company_name'. Try a more specific query."}
  ],
  "hint": "Fix or remove these values. Send \"partial\": true to run the search without them; the rest of each filter still applies.",
  "credit_used": 0,
  "request_id": "..."
}
```

Titles resolve against LinkedIn's own typeahead, so write them the way LinkedIn lists them: full words, in English, no abbreviations (`"Customer Success Manager"`, not `"CSM"`). A phrase LinkedIn does not standardise belongs in `keywords`. An unknown field *name* is reported in `filter_errors` but does not refuse the search.

## Response

```json Request theme={null}
{
  "company_linkedin_urls": [
    "https://www.linkedin.com/company/salesforce/",
    { "value": "https://www.linkedin.com/company/competitor-co/", "exclude": true }
  ],
  "company_ids": [1441, { "value": 9876, "exclude": true }],
  "seniority": ["CXO", "Vice President"],
  "keywords": "Representative Director",
  "page": 1
}
```

```json Response theme={null}
{
  "success": true,
  "results": [
    {
      "full_name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "location": "San Francisco Bay Area",
      "title": "Chief Technology Officer",
      "company": "Stripe",
      "company_id": "2135371",
      "is_current": true,
      "started_on": { "month": 9, "year": 2022 },
      "tenure_years": 3,
      "tenure_months": 2,
      "summary": null,
      "profile_url": "https://www.linkedin.com/sales/lead/ACwAAABcDeFgHiJkLmNoPqRsTuVwXyZ01234,NAME_SEARCH",
      "profile_picture": "https://media.licdn.com/dms/image/...",
      "open_link": false
    }
  ],
  "pagination": {
    "page": 1,
    "total": 247,
    "count": 25,
    "start": 0
  },
  "filters_applied": 4,
  "filter_errors": [],
  "credit_used": 10
}
```

## Response fields

**success** `boolean`

`true` on success.

**results** `array`

List of matching people profiles.

**Profile object**

**full\_name** `string`

Full name.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**location** `string`

Geographic region.

**title** `string`

Current job title.

**company** `string`

Current company name.

**company\_id** `string`

LinkedIn company id of the role shown in `title` and `company` (nullable). A company filter matches a person's current roles, and the role shown here is their primary one, so compare this id with the company you searched for if you need exactly that role.

**is\_current** `boolean`

Whether the role shown is a current one (nullable).

**started\_on** `object`

Start of the role shown, as `{month, year}` (nullable).

**tenure\_years** `integer`

Years in current role (nullable).

**tenure\_months** `integer`

Months in current role (nullable).

**summary** `string`

Profile summary (nullable).

**profile\_url** `string`

Sales Navigator lead URL. The person is identified by URN rather than a vanity slug, so this URL does **not** resolve anonymously — fetching it unauthenticated returns HTTP `999` from LinkedIn. Treat it as a stable identifier for the lead, not as a page to fetch.

**profile\_picture** `string`

Profile picture URL (nullable).

**open\_link** `boolean`

Whether the profile is an OpenLink profile.

**pagination** `object`

**Pagination object**

**page** `integer`

Current page number.

**total** `integer`

Total results across all pages.

**count** `integer`

Results on this page.

**start** `integer`

Offset of the first result.

**filters\_applied** `integer`

Number of filters applied to this search.

**filter\_errors** `array`

Every value that was dropped from this search, one entry each with `field`, `value` and `error`, plus any unknown field names. Only non-empty on a `partial: true` request or when an unknown field name was sent; otherwise a refused value is a `422` (see Refused values above).

**credit\_used** `integer`

Credits actually charged for this request. A request that returns no results, or that fails before reaching the search, is charged `0`.


# ICP Search — Filter Reference
Source: https://docs.datamagnet.co/api-reference/endpoints/icp-search-filters

Complete reference for every filter available in the Datamagnet ICP Search endpoints, including job title, seniority, industry, headcount, and location.

# ICP Search Filter Reference

All filter values are human-readable strings — no internal IDs required. Pass them directly in your search request.

Use `GET /api/v1/people-search/filters` to retrieve all valid values at once — useful for populating dropdowns. No credits consumed.

```bash theme={null}
curl https://api.datamagnet.co/api/v1/people-search/filters \
  -H "Authorization: Bearer <your_api_key>"
```

> [!NOTE]
>
> Filters come in two kinds, and `/people-search/filters` reports both.
>
> **Closed vocabularies** — seniority, headcount, company type, function, industry and the rest — have a fixed set of values, listed under `filters`. Pick from those exactly.
>
> **Free-text filters** — `location`, `job_title`, `company_name`, `school`, `technology` — are resolved from whatever string you send, so they have no value list. They are listed under `filters.dynamic_fields` with a description instead of values. Use [`/people-search/suggest`](/api-reference/endpoints/icp-suggest) to preview how a given string will resolve.

***

## Seniority level

Filter people by their seniority level in the organization.

| Value | Aliases |
| - | - |
| `Owner` | |
| `Partner` | |
| `CXO` | `C-Level` |
| `Vice President` | `VP` |
| `Director` | |
| `Experienced Manager` | `Manager` |
| `Entry Level Manager` | |
| `Strategic` | |
| `Senior` | |
| `Entry Level` | |
| `In Training` | `Intern` |

**Example:**

```json theme={null}
{ "seniority": ["CXO", "Vice President", "Director"] }
```

***

## Company headcount

Filter by the number of employees at the company.

| Value |
| - |
| `Self-Employed` |
| `1-10` |
| `11-50` |
| `51-200` |
| `201-500` |
| `501-1,000` |
| `1,001-5,000` |
| `5,001-10,000` |
| `10,001+` |

**Example:**

```json theme={null}
{ "company_headcount": ["501-1,000", "1,001-5,000"] }
```

***

## Company type

| Value | Aliases |
| - | - |
| `Public` | `Public Company` |
| `Private` | `Privately Held` |
| `Non Profit` | `Nonprofit` |
| `Educational` | `Educational Institution` |
| `Partnership` | |
| `Self Employed` | |
| `Government` | `Government Agency` |

**Example:**

```json theme={null}
{ "company_type": "Public" }
```

***

## Company name

Pass any company name as a string. Accepts a single value or an array.

**Example:**

```json theme={null}
{ "company_name": "Stripe" }
```

```json theme={null}
{ "company_name": ["Stripe", "Plaid"] }
```

***

## Job title

Pass any job title as a string. Accepts a single value or an array.

**Example:**

```json theme={null}
{ "job_title": "CTO" }
```

```json theme={null}
{ "job_title": ["CTO", "Chief Technology Officer"] }
```

***

## Location

City, region, or country. Accepts a single value or an array.

**Example:**

```json theme={null}
{ "location": "San Francisco" }
```

```json theme={null}
{ "location": ["San Francisco", "New York", "London"] }
```

***

## Industry

Over 300 industries are supported. Values are case-insensitive and partial matching is supported (e.g. `"software"` matches `"Software Development"`). Use `GET /api/v1/people-search/filters` to get the full sorted list.

**Sample values:**

```
Software Development, Financial Services, Healthcare, Manufacturing,
Retail, Education, Real Estate, Consulting, Marketing Services,
IT Services and IT Consulting, Banking, Insurance, ...
```

**Example:**

```json theme={null}
{ "industry": "Software Development" }
```

***

## School

University or school name. Accepts a single value or an array.

**Example:**

```json theme={null}
{ "school": "MIT" }
```

***

## Technology

Technologies used by the person's company. Accepts a single value or an array.

**Example:**

```json theme={null}
{ "technology": ["Salesforce", "HubSpot"] }
```

***

## Function / department

Filter by the person's functional department.

| Value |
| - |
| `Accounting` |
| `Administrative` |
| `Arts and Design` |
| `Business Development` |
| `Consulting` |
| `Customer Success` |
| `Education` |
| `Engineering` |
| `Entrepreneurship` |
| `Finance` |
| `Healthcare` |
| `Human Resources` |
| `Information Technology` |
| `Legal` |
| `Marketing` |
| `Media` |
| `Military` |
| `Operations` |
| `Product Management` |
| `Program Management` |
| `Purchasing` |
| `Quality Assurance` |
| `Real Estate` |
| `Research` |
| `Sales` |
| `Support` |

**Example:**

```json theme={null}
{ "function": ["Engineering", "Product Management"] }
```

***

## Years in current position

| Value | Aliases |
| - | - |
| `Less than 1 year` | `<1` |
| `1 to 2 years` | `1-2` |
| `3 to 5 years` | `3-5` |
| `6 to 10 years` | `6-10` |
| `More than 10 years` | `10+` |

**Example:**

```json theme={null}
{ "years_in_position": "1 to 2 years" }
```

***

## Followers count

Filter by the number of LinkedIn followers.

| Value |
| - |
| `1-50` |
| `51-100` |
| `101-1000` |
| `1001-5000` |
| `5001+` |

**Example:**

```json theme={null}
{ "followers_count": "1001-5000" }
```

***

## Recent activities

Filter by recent company activity signals.

| Value | Aliases |
| - | - |
| `Funding` | `Funding Events` |
| `Leadership Changes` | `Senior Leadership Changes` |

**Example:**

```json theme={null}
{ "recent_activities": "Funding" }
```

***

## Job opportunities

Filter to companies actively hiring.

| Value |
| - |
| `Hiring` |

**Example:**

```json theme={null}
{ "job_opportunities": "Hiring" }
```

***

## Recently changed jobs

Sales Navigator's **Changed jobs** spotlight: people who recently started a new position. LinkedIn decides what counts as recent — the filter carries no date range of its own.

It is a single checkbox in Sales Navigator, so it has one value.

| Value | Aliases |
| - | - |
| `Changed Jobs` | `Recently Changed Jobs`, `Job Change` |

**Example:**

```json theme={null}
{ "recently_changed_jobs": "Changed Jobs" }
```

A boolean works too, which usually reads better for a one-value filter:

```json theme={null}
{ "recently_changed_jobs": true }
```

> [!NOTE]
>
> `false` means *do not filter on this* and is the same as leaving the field out — not "people who have **not** changed jobs". Sales Navigator offers this spotlight as an include-only checkbox, so there is no tested way to ask for the opposite.

Combine it with the filters that describe who you are looking for:

```json theme={null}
{
  "recently_changed_jobs": true,
  "seniority": ["CXO", "Owner", "Vice President"],
  "company_headcount": ["1-10", "11-50"],
  "industry": "Telecommunications",
  "location": "United States"
}
```

***

## Posted on LinkedIn

Sales Navigator's **Posted on LinkedIn** spotlight: people who have recently posted on LinkedIn. LinkedIn decides what counts as recent — the filter carries no date range of its own.

Like **Changed jobs**, it is a single checkbox in Sales Navigator with one value.

| Value | Aliases |
| - | - |
| `Posted on LinkedIn` | `Recently Posted`, `Posted Recently` |

**Example:**

```json theme={null}
{ "posted_on_linkedin": true }
```

> [!NOTE]
>
> `false` means *do not filter on this* and is the same as leaving the field out — not "people who have **not** posted". Sales Navigator offers this spotlight as an include-only checkbox, so there is no tested way to ask for the opposite.

It combines with the other filters, including **Changed jobs**:

```json theme={null}
{
  "posted_on_linkedin": true,
  "seniority": ["CXO", "Owner", "Vice President"],
  "company_headcount": ["1-10", "11-50"],
  "industry": "Telecommunications",
  "location": "United States"
}
```

***

## Profile language

Filter by the language the person's profile is written in.

| Value | Value | Value |
| - | - | - |
| `Arabic` | `English` | `Spanish` |
| `Portuguese` | `Chinese` | `French` |
| `Italian` | `Russian` | `German` |
| `Dutch` | `Turkish` | `Tagalog` |
| `Polish` | `Korean` | `Japanese` |
| `Malay` | `Norwegian` | `Danish` |
| `Romanian` | `Swedish` | `Indonesian` |
| `Czech` | | |

**Example:**

```json theme={null}
{ "profile_language": "English" }
```

***

## Include / exclude syntax

Every filter supports negative matching. To exclude a value, wrap it in an object with `"exclude": true`:

```json theme={null}
{
  "company_name": [
    "Stripe",
    { "value": "PayPal", "exclude": true }
  ]
}
```

This returns people who work at Stripe **but not** PayPal.

Explicit form using `selection`:

```json theme={null}
{ "value": "PayPal", "selection": "EXCLUDED" }
```


# ICP Search — Suggest
Source: https://docs.datamagnet.co/api-reference/endpoints/icp-suggest

GET https://api.datamagnet.co/api/v1/people-search/suggest/{suggest_type}
Autocomplete suggestions for ICP Search filter fields including company name, job title, industry, and location for building typeahead UIs.

# ICP Search Suggest

**Cost:** `1` credit.

Returns typeahead suggestions for filter fields such as company name, job title, location, school, and technology. Useful for building autocomplete dropdowns in your UI.

Results are cached server-side for fast repeated lookups.

## Path parameters

**suggest\_type** `string` *required*

The type of suggestion to retrieve. Must be one of:

| Value | Used for |
| - | - |
| `company` | `company_name` filter |
| `job_title` | `job_title` filter |
| `location` | `location` filter |
| `school` | `school` filter |
| `technology` | `technology` filter |
| `function` | `function` filter |

## Query parameters

**q** `string` *required*

The search query string.

Example: `?q=Stripe`

## Example

```bash theme={null}
curl "https://api.datamagnet.co/api/v1/people-search/suggest/company?q=Stripe" \
  -H "Authorization: Bearer <your_api_key>"
```

```json Response theme={null}
{
  "success": true,
  "results": [
    {
      "label": "Stripe",
      "value": "Stripe",
      "id": "15285098",
      "meta": {
        "employees": "1001-5000",
        "industry": "Financial Services",
        "location": "US",
        "logo": "https://media.licdn.com/dms/image/..."
      }
    },
    {
      "label": "Stripe Japan",
      "value": "Stripe Japan",
      "id": "67890123",
      "meta": {
        "employees": "51-200",
        "industry": "Financial Services",
        "location": "JP",
        "logo": null
      }
    }
  ],
  "cached": false
}
```

## Response fields

**success** `boolean`

`true` on success.

**results** `array`

List of matching suggestions. The top result is the best match.

**Suggestion object**

**label** `string`

Display label shown in UI.

**value** `string`

The string to pass in a search request.

**id** `string`

Internal identifier.

**meta** `object`

Additional context. Fields vary by type:

* **company**: `employees`, `industry`, `location`, `logo`
* **school**: `employees`, `location`
* **location**: `headline`

**cached** `boolean`

`true` if the result was served from the server-side cache.


# Job Change Search
Source: https://docs.datamagnet.co/api-reference/endpoints/job-changes-search

POST https://api.datamagnet.co/api/v1/job-changes/search
Search job-change events — people starting a new role, leaving a company, or being promoted — filtered by company, title, location and recency.

# Job Change Search

**Cost:** `10` credits per page. A page with no matches costs `0`.

Job changes are the highest-intent signal in B2B: a new VP of Engineering buys differently in week three than in month nine, and the person who just left your customer is the reason that account is about to churn. This endpoint returns those events as a feed you can poll.

Each event says what happened (`joined`, `left`, `title_change`), when it happened, when we detected it, and who it happened to — with the person and the company already attached, so a single call gives you something you can act on without a second lookup.

## Freshness, and why staleness is ordered rather than hidden

Results are sorted by freshness. The feed opens with same-day detections; events we detected long after the fact surface as you page deeper.

Every real dated event is included — a stale one is ordered later, never dropped. Each event carries `detection_lag_days`, the number of days between the change happening and our detection of it. Lower is fresher.

> [!TIP]
>
> Poll page `1` on a schedule and stop as soon as `detection_lag_days` exceeds what you have already processed. That gives you the new events without paging through history every run.

## Request body

**event\_type** `string`

Restrict to one kind of event. Omit to receive all three.

| Value | Meaning |
| - | - |
| `joined` | The person started a new position at the company. |
| `left` | The person is no longer at the company. |
| `title_change` | The person's title changed at the same company. |

**organization\_ids** `string | string[]`

Filter to specific companies, by the `organization_id` returned on every event. Exact match, and more precise than a name search.

Accepts an array or a comma-separated string. Up to 50 companies per request, counted across this field and `company_urls` together.

```json theme={null}
"organization_ids": ["dm_org_edmab4ei56y3w6cgktcgegllpqrxdbnlt4aqk"]
```

**company\_urls** `string | string[]`

Filter to specific companies by LinkedIn company URL, or by the slug at the end of one. Use this the first time you track a company, when you do not have its `organization_id` yet — the response gives you the id to use from then on.

```json theme={null}
"company_urls": ["https://www.linkedin.com/company/stripe/", "figma"]
```

A company we do not yet track returns `400`. Resolving a URL is slower than passing an id, so prefer the id once you have it.

**title** `string`

Word-match on the new job title. Minimum 3 characters.

Example: `"Engineering"` matches `VP of Engineering` and `Engineering Manager`.

**geo\_city** `string`

Partial match on the person's current city. Minimum 3 characters.

Example: `"Berlin"`

**geo\_country\_code** `string`

Two-letter country code for the person's current location. Case-insensitive.

Example: `"DE"`

> [!NOTE]
>
> The two geo filters narrow the search but are not echoed back on the events — they filter on a location the event record does not carry. If you need the person's location, fetch their profile with `person.linkedin_url`.

**days\_ago** `integer`

Recency window on the **detection** time, in days. Range `1`–`365`. Omit it to search all events.

Example: `7` returns everything detected in the last week, whenever the change itself happened.

**page** `integer` (default: 1)

Page number, 1-based. Maximum `10000`; anything higher returns `400`.

**limit** `integer` (default: 25)

Events per page. Range `1`–`50`.

> [!NOTE]
>
> This endpoint also accepts `GET` with the same attributes as query parameters, e.g.
> `GET /api/v1/job-changes/search?event_type=joined&days_ago=7&title=Engineering`.
>
> In a query string, list fields are comma-separated: `?organization_ids=dm_org_abc,dm_org_def`.

***

## Company filter options

Two ways to name a company — use whichever you have:

| Field | What you provide | Cost |
| - | - | - |
| `organization_ids` | An `organization_id` from a previous response | Fastest; no extra work |
| `company_urls` | A LinkedIn company URL or slug | One resolution step the first time each company is seen |

Both can be combined in the same request. A company named by both counts once.

***

## Working with ids

Every event carries two Datamagnet ids:

* `person.profile_id` — `dm_prsn_…`
* `organization.organization_id` — `dm_org_…`

They are stable: the same person and the same company are the same id in every response, for ever, so they work as keys in your own database. `organization_id` is Datamagnet's own identifier for that company — the same one our company records are keyed by — so an id you store today keeps working as we add more about that company.

To pull the full record behind an event, use the LinkedIn URL that comes with it:

* `person.linkedin_url` → [Person](/api-reference/endpoints/people)
* `organization.linkedin_url` → [Company](/api-reference/endpoints/company)

***

## Response

```json Request theme={null}
{
  "event_type": "joined",
  "title": "Engineering",
  "geo_country_code": "DE",
  "days_ago": 7,
  "page": 1,
  "limit": 25
}
```

```json Response theme={null}
{
  "success": true,
  "message": "Job change events retrieved successfully",
  "data": [
    {
      "event_type": "title_change",
      "detected_at": "2026-05-01T17:20:04.389921Z",
      "changed_at": "2026-05-01T00:00:00Z",
      "detection_lag_days": 0,
      "title": {
        "current": "Data Engineer",
        "previous": "Data Analyst"
      },
      "person": {
        "profile_id": "dm_prsn_tnd66ysw4lmt4yighsalfnmf2tcanlpmp3exh6q",
        "handle": "lecomte-quentin",
        "full_name": "Quentin Lecomte",
        "first_name": "Quentin",
        "last_name": "Lecomte",
        "headline": "Data Engineer @ Aktivco | Camusat Group",
        "linkedin_url": "https://linkedin.com/in/lecomte-quentin"
      },
      "organization": {
        "organization_id": "dm_org_33u32yb3sh56d6jxiw3lzljselgver2p4ons6",
        "name": "AktivCo",
        "slug": "activco",
        "linkedin_url": "https://www.linkedin.com/company/activco"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "has_more": true
  },
  "credit_used": 10
}
```

Every event returns the same set of keys. A field an event does not have comes back as `null` rather than being omitted, so your parsing code never has to branch.

### Dates, and the two of them

`changed_at` is when the change took effect. `detected_at` is when we saw it. `detection_lag_days` is the gap, in days.

`title.previous` is only meaningful on `title_change` and `left`; a `joined` event has no title to have replaced, so it comes back `null`.

### Pagination

`pagination.has_more` tells you whether another page exists. Keep incrementing `page` while it is `true`, up to the `10000` page cap.

An empty `data` array with `has_more: false` means you have reached the end of the feed for those filters — and costs `0` credits.

***

## Errors

| Status | Meaning | What to do |
| - | - | - |
| `400` | A filter was invalid — an unknown `event_type`, a text filter under 3 characters, `days_ago` outside 1–365, `limit` above 50, a page above 10000, or a company we do not track. `message` names the problem. | Fix the request. Nothing is charged. |
| `401` | Missing or invalid API key. | Send your key as `Authorization: Bearer YOUR_API_KEY` — see [Authentication](/api-reference/authentication). |
| `403` | Your plan does not include job change data. | Contact us at [signals@datamagnet.co](mailto:signals@datamagnet.co). |
| `429` | Rate limit for your plan exceeded. | Back off and retry; see the `X-RateLimit-*` response headers. |
| `503` | Job change search is temporarily unavailable — temporary capacity limits, not a fault in your request. | Retry after the number of seconds in the `Retry-After` header: `60` when the search is being rate limited, longer when capacity is exhausted. Nothing is charged. |

Nothing is charged on any error.


# Job Details
Source: https://docs.datamagnet.co/api-reference/endpoints/job-details

POST https://api.datamagnet.co/api/v1/jobs/detail
Fetch a LinkedIn job posting by job ID or URL — title, description, location, seniority, employment type, workplace type, apply links, application counts and the hiring company.

# Job Details

**Cost:** `1` credit / successful request. (`include_hiring_team` adds `1` credit, charged only when the section is returned.)

Get structured data for a single LinkedIn job posting. Provide either the numeric job ID or any LinkedIn job URL — the API extracts the ID for you.

`data` is the posting itself: its own fields, the apply counts and links alongside them, and the hiring company nested under `company_info`. Every request returns the same set of keys; a field a posting does not publish comes back as `null` rather than being omitted, so your parsing code never has to branch.

## Job details endpoint

### Required attributes

**job\_id** `string`

The numeric LinkedIn job posting ID, e.g. `"4443378596"`.

Either `job_id` or `url` is required. If both are supplied, `job_id` wins.

**url** `string`

Any LinkedIn job URL. The posting ID is extracted automatically from all common formats:

* `https://www.linkedin.com/jobs/view/4443378596`
* `https://www.linkedin.com/jobs/view/generative-ai-engineer-at-hcltech-4443378596`
* `https://www.linkedin.com/jobs/search/?currentJobId=4443378596`

### Optional attributes

**include\_hiring\_team** `boolean` (default: false)

Adds the `hiring_team` key: the job poster and any recruiters LinkedIn lists on the posting, with their name, headline, profile URL and photo.

Costs an additional `1` credit, charged only when the section is returned. A posting with nobody listed returns an empty `members` array and is billed; a posting whose hiring team could not be retrieved omits the key entirely and is not billed.

> [!NOTE]
>
> This endpoint also accepts `GET` with the same attributes as query parameters, e.g.
> `GET /api/v1/jobs/detail?job_id=4443378596&include_hiring_team=true`.

### Response

```json Response theme={null}
{
  "success": true,
  "message": "response retrieved successfully",
  "data": {
    "title": "Generative AI Engineer",
    "standardized_title": "Generative AI Engineer",
    "description": "🚀 HCLTech Exclusive Walk-In Drive | AIML Developer - Are you passionate about Artificial Intelligence, Machine Learning, and Generative AI?...",
    "description_html": "<p>🚀 <strong>HCLTech Exclusive Walk-In Drive | AIML Developer </strong>- Are you passionate about...</p><ul><li>Lead AI/ML solution development using Python</li></ul>",
    "location": "Noida, Uttar Pradesh, India",
    "location_id": "104869687",
    "employment_status": "Full-time",
    "is_remote_allowed": false,
    "is_third_party_sourced": false,
    "listed_at": "2026-07-21T13:36:54Z",
    "expire_at": "2026-08-20T13:36:54Z",
    "closed_at": null,
    "job_url": "https://www.linkedin.com/jobs/view/4443378596",
    "experience_level": "Associate",
    "industries": ["IT Services and IT Consulting"],
    "job_functions": ["Engineering", "Research"],
    "is_new": false,
    "original_listed_at": "2026-07-21T13:36:54Z",
    "job_state": "LISTED",
    "workplace_types": ["ONSITE"],
    "country_code": "in",
    "job_posting_id": "4443378596",
    "is_reposted": false,
    "job_application_limit_reached": false,
    "eligible_for_referrals": false,
    "posted_time_ago": "3 weeks ago",
    "seniority_level": "Associate",
    "salary": null,
    "salary_min": null,
    "salary_max": null,
    "salary_currency": null,
    "salary_period": null,
    "benefits": null,
    "required_skills": [],
    "applicant_tracking_system": "LinkedIn",
    "total_applies": 0,
    "total_views": 0,
    "is_application_limit_reached": false,
    "application_url": "https://www.linkedin.com/job-apply/4443378596",
    "is_easy_apply": true,
    "applicant_count_text": null,
    "company_info": {
      "name": "HCLTech",
      "description": "HCLTech is a global technology company, home to more than 223,000 people across 60 countries...",
      "staff_count": 257915,
      "industries": ["IT Services and IT Consulting"],
      "specialities": ["Manufacturing", "Aerospace & Defense", "Financial Services", "Telecom"],
      "universal_name": "hcltech",
      "headquarters": {
        "line1": null,
        "city": "Noida",
        "geographicArea": "Uttar Pradesh",
        "postalCode": "201301",
        "country": "IN",
        "$type": "com.linkedin.common.Address"
      },
      "url": "https://www.linkedin.com/company/hcltech",
      "logo_url": "https://media.licdn.com/dms/image/v2/C4D0BAQF-RIoeeMTMKQ/company-logo_200_200/...",
      "background_cover_url": "https://media.licdn.com/dms/image/v2/D4D3DAQEVwVTGwE1eXA/image-scale_191_1128/...",
      "company_id": "1756",
      "website": null,
      "followers": 9571613,
      "company_size": "10001+",
      "company_type": null,
      "founded_year": null
    }
  },
  "credit_used": 1,
  "credit_addon": 0
}
```

## The job details model

### Properties

**success** `boolean`

Whether the posting was retrieved.

**message** `string`

A human-readable status. On failure this explains what went wrong.

**credit\_used** `integer`

Credits charged for the posting itself. `0` on any error response.

**credit\_addon** `integer`

Extra credits charged for optional sections that were returned.

**data** `object | null`

The job posting. `null` on any error response.

**Data object**

#### Identity

**title** `string`

The job title as written on the posting.

**standardized\_title** `string | null`

LinkedIn's normalized title for the role, e.g. a posting titled `"Gen AI Engineer"` standardizes to `"Artificial Intelligence Engineer"`. Useful for grouping postings that describe the same job in different words.

**job\_posting\_id** `string`

The numeric posting ID, as a string.

**job\_url** `string`

Canonical LinkedIn URL for the posting, free of tracking parameters.

#### Description

**description** `string`

The full job description as plain text, with paragraph and bullet breaks preserved.

**description\_html** `string | null`

The same description as HTML — `<p>`, `<ul>`/`<li>`, `<strong>` and `<em>` — ready to render. Text is HTML-escaped.

#### Location

**location** `string`

The location as written on the posting, e.g. `"Noida, Uttar Pradesh, India"`.

**location\_id** `string | null`

LinkedIn's internal geo ID for the location, stable across postings in the same place.

**country\_code** `string | null`

Two-letter country code for the posting's location, lower-case, e.g. `"in"`.

**workplace\_types** `array`

Where the work happens: `["ONSITE"]`, `["REMOTE"]` or `["HYBRID"]`.

**is\_remote\_allowed** `boolean | null`

Whether the posting allows remote work.

#### Classification

**employment\_status** `string | null`

Employment type: `"Full-time"`, `"Part-time"`, `"Contract"`, `"Internship"`, `"Temporary"`, `"Volunteer"`, `"Other"`.

**experience\_level** `string | null`

Seniority as LinkedIn labels it: `"Internship"`, `"Entry level"`, `"Associate"`, `"Mid-Senior level"`, `"Director"`, `"Executive"`, `"Not Applicable"`.

**seniority\_level** `string | null`

Alias of `experience_level`.

**industries** `array`

Industries the posting is filed under, e.g. `["IT Services and IT Consulting"]`.

**job\_functions** `array`

Job functions, e.g. `["Engineering", "Research"]`.

**required\_skills** `array`

Skills listed on the posting, when the posting lists them.

**applicant\_tracking\_system** `string | null`

The ATS the posting is administered through, e.g. `"LinkedIn"`, when the posting names one.

#### Compensation

**salary** `string | null`

The salary range exactly as displayed, e.g. `"$120,000.00/yr - $150,000.00/yr"`. Most postings do not publish one.

**salary\_min** `number | null`

Lower bound of the range.

**salary\_max** `number | null`

Upper bound of the range.

**salary\_currency** `string | null`

Currency symbol or code detected in the range, e.g. `"$"`.

**salary\_period** `string | null`

Pay period: `"YEARLY"`, `"MONTHLY"`, `"WEEKLY"` or `"HOURLY"`.

**benefits** `string | null`

The benefits listed on the posting, when present.

#### Timing and state

**listed\_at** `string | null`

When the posting went live, as an ISO 8601 UTC timestamp, e.g. `"2026-07-21T13:36:54Z"`. All timestamps use this format.

**original\_listed\_at** `string | null`

When the posting first went live, which differs from `listed_at` on reposted jobs.

**expire\_at** `string | null`

When the posting expires.

**closed\_at** `string | null`

When the posting stopped accepting applications. `null` while it is still open.

**posted\_time\_ago** `string | null`

Age of the posting in words, e.g. `"3 weeks ago"`.

**is\_new** `boolean | null`

Whether the posting went up within the last 24 hours.

**is\_reposted** `boolean | null`

Whether the posting is a repost of an earlier one.

**job\_state** `string | null`

`"LISTED"` while the posting accepts applications, `"CLOSED"` once it stops.

**job\_application\_limit\_reached** `boolean | null`

Whether the posting has hit its application limit.

**is\_third\_party\_sourced** `boolean | null`

Whether a staffing agency, rather than the employer, posted the job.

**eligible\_for\_referrals** `boolean | null`

Whether LinkedIn offers a referral path on the posting.

#### Applying

**application\_url** `string | null`

Where applications go — the employer's site for off-LinkedIn postings, the LinkedIn apply link for Easy Apply ones. `null` when the posting takes applications without a link.

**is\_easy\_apply** `boolean | null`

Whether the application stays on LinkedIn rather than going to an external site.

**total\_applies** `integer | null`

Number of applications received.

**total\_views** `integer | null`

Number of times the posting has been viewed.

**applicant\_count\_text** `string | null`

The applicant count as LinkedIn phrases it, e.g. `"Over 200 applicants"`, when the posting shows it that way.

**is\_application\_limit\_reached** `boolean | null`

Whether the posting has stopped accepting applications.

#### Company info

**company\_info** `object`

The hiring company.

**Company info object**

**name** `string`

Company name.

**description** `string | null`

The company's About description.

**url** `string | null`

The company's LinkedIn page URL.

**universal\_name** `string | null`

The company's LinkedIn slug, e.g. `"hcltech"`.

**company\_id** `string | null`

LinkedIn's numeric company ID.

**logo\_url** `string | null`

Company logo image URL.

**background\_cover\_url** `string | null`

Cover image on the company page.

**industries** `array`

Industries the company operates in.

**specialities** `array`

The specialities listed on the company page.

**staff\_count** `integer | null`

Number of employees on LinkedIn.

**company\_size** `string | null`

Headcount bracket, written as a plain range: `"51-200"`, `"1001-5000"`, `"10001+"`.

**followers** `integer | null`

LinkedIn follower count.

**headquarters** `object`

The company's registered head office.

**Headquarters object**

**line1** `string | null`

Street address.

**city** `string | null`

City.

**geographicArea** `string | null`

State, province or region.

**postalCode** `string | null`

Postal code.

**country** `string | null`

Two-letter country code, upper-case.

**website** `string | null`

The company's own website.

**company\_type** `string | null`

Organization type, e.g. `"Public Company"`.

**founded\_year** `string | null`

Year the company was founded.

#### Hiring team

**hiring\_team** `object`

The people LinkedIn lists on the posting. Present only when `include_hiring_team` was set and the section was returned — check for the key rather than for a `null`.

**Hiring team object**

**total** `integer`

Number of people on the hiring team.

**members** `array`

The team members.

**Member object**

**name** `string`

Full name.

**headline** `string`

LinkedIn headline.

**role** `string`

Their role on the posting, e.g. `"Job poster"`.

**url** `string`

Link to their LinkedIn profile.

**username** `string`

Their LinkedIn public identifier.

**urn** `string`

LinkedIn's internal profile identifier.

**profile\_picture\_url** `string`

Profile photo URL.

## Hiring team example

With `include_hiring_team` set to `true`, the `hiring_team` key is added to `data`:

```json hiring_team theme={null}
"hiring_team": {
  "members": [
    {
      "name": "Mahima Prajapati",
      "headline": "HR Professional || Talent Acquisition Specialist || IT Recruitment",
      "urn": "ACoAADaj6F0BDLJlkkLSMH-0i05H1wQ5quh9Htk",
      "username": "mahima-prajapati-425008217",
      "url": "https://www.linkedin.com/in/mahima-prajapati-425008217",
      "profile_picture_url": "https://media.licdn.com/dms/image/v2/D5603AQGxk.../profile-displayphoto-shrink_800_800/...",
      "role": "Job poster"
    }
  ],
  "total": 1
}
```

## Field availability

Every response carries every key. What varies is what the posting itself publishes:

| Field | Filled when |
| - | - |
| `salary`, `salary_min`, `salary_max`, `salary_currency`, `salary_period` | The employer published a pay range. Most do not. |
| `benefits`, `required_skills` | The employer listed them on the posting. |
| `closed_at` | The posting has closed. `null` while `job_state` is `"LISTED"`. |
| `application_url` | Applications go to a URL — an employer site, or a LinkedIn apply link. |
| `applicant_count_text` | The posting displays a phrased applicant count. |
| `standardized_title`, `applicant_tracking_system` | LinkedIn classified the role / named the ATS. |
| `company_info.website`, `company_type`, `founded_year` | Published on the company page. |
| `hiring_team` | `include_hiring_team` was set and the section was returned. |

## Credits

| Request | Credits |
| - | - |
| Job posting | 1 |
| With `include_hiring_team` | 2 |

An optional section that could not be returned is not charged. Failed requests (`4xx`, `5xx`) are never charged.

## Errors

| Status | Meaning |
| - | - |
| `400` | Neither `job_id` nor `url` was supplied, or the URL contains no job ID. |
| `404` | The posting does not exist, or has been removed by the poster. |
| `502` | The posting exists but could not be retrieved. Retry shortly. |

## Example

```python Example theme={null}
import requests

url = "https://api.datamagnet.co/api/v1/jobs/detail"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.post(url, json={
    "job_id": "4443378596",
    "include_hiring_team": True
}, headers=headers)

job = response.json()["data"]
company = job["company_info"]

print(f"{job['title']} at {company['name']} — {job['location']}")
print(f"{job['employment_status']} · {job['experience_level']} · {job['workplace_types'][0]}")
print(f"Posted {job['posted_time_ago']} · {job['total_applies']} applies · {job['total_views']} views")
print(f"Apply: {job['application_url'] or 'on LinkedIn'}")

for member in job.get("hiring_team", {}).get("members", []):
    print(f"  {member['role']}: {member['name']} — {member['url']}")
```


# People Profile
Source: https://docs.datamagnet.co/api-reference/endpoints/people

POST https://api.datamagnet.co/api/v1/person
Fetch structured data for a LinkedIn personal profile including name, headline, current role, experience, education, skills, and contact info.

# People

**Cost:** `1` credit / successful request. (Extra charges might be incurred if premium optional parameters are used. Please read the description of the parameters that you intend to use)

Each enrichment flag below costs an additional **2 credits**, charged only when that specific enrichment succeeds. If a requested enrichment fails after retries, the base profile request still succeeds and the corresponding field is returned with a generic error — you are not charged for that failed enrichment.

Get structured data of a Personal Profile.

## Person profile endpoint

This endpoint allows you to get structured data of a Personal Profile.

### Required attributes

**url** `string` *required*

The LinkedIn URL of the person.

### Optional attributes

**use\_cache** `string`

Alters the caching behavior.

* `if-present` - The default behavior. Fetches profile from cache regardless of age of profile. If the profile is not available in cache, the API fetches it live.
* `if-recent` - API will make a best effort to return a fresh profile no older than 29 days.
* `never` - Do not ever read profile from cache.

**lang** `string`

The language in which you need your response.

### Enrichment flags

Each of the following flags is `false` by default. Set a flag to `true` to make an additional request and append the corresponding field to the response. Every additional request that succeeds is retried automatically on transient failures, and costs an extra **2 credits** on top of the base endpoint cost.

**company\_interest** `boolean`

Appends the list of companies the profile follows to `company_interest`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

**top\_voices\_interest** `boolean`

Appends the list of LinkedIn Top Voices the profile follows to `top_voices_interest`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

**group\_interest** `boolean`

Appends the list of LinkedIn Groups the profile is a member of to `group_interest`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

**school\_interest** `boolean`

Appends the list of schools the profile follows to `school_interest`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

**newsletter\_interest** `boolean`

Appends the list of LinkedIn Newsletters the profile is subscribed to `newsletter_interest`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

**similar\_profiles** `boolean`

Appends a list of profiles similar to this one to `similar_profiles`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

**recommendations\_data** `boolean`

Appends the full profile bundle plus given/received recommendations to `recommendations_data`.

Costs an additional `2` credit, subject to data availability, on top of the base endpoint cost.

### Enrichment pages

`company_interest`, `group_interest`, `school_interest` and `newsletter_interest` return one page at a time. Send the page number you want; the response carries `current_page` and `total_pages`. Each request for another page is a new request and costs the enrichment credits again.

**company\_interest\_page** `number`

Page of `company_interest` to return. Defaults to `1`.

**group\_interest\_page** `number`

Page of `group_interest` to return. Defaults to `1`.

**school\_interest\_page** `number`

Page of `school_interest` to return. Defaults to `1`.

**newsletter\_interest\_page** `number`

Page of `newsletter_interest` to return. Defaults to `1`.

Error response:

```json theme={null}
{
  "company_interest": {
    "error": "Unable to fetch this data at this time."
  }
}
```

### Response

```json Response theme={null}
{
  "message": {
    "email": "",
    "full_name": "Jane Doe",
    "first_name": "Jane",
    "last_name": "Doe",
    "middle_name": "",
    "display_name": "Jane Doe",
    "unformatted_full_name": "Jane Doe",
    "username": "jane-doe-example",
    "profile_link": "https://linkedin.com/in/jane-doe-example",
    "linkedin_id": "2980124",
    "sales_id": "urn:li:fsd_profile:ACoAAAExampleUrnNotARealMember",
    "linkedin_sales_link": "",
    "phone_number": null,
    "twitter_link": "",
    "pronoun": "she/her",
    "avatar_url": "https://media.licdn.com/dms/image/.../profile-displayphoto-shrink_800_800/...",
    "background_picture": "",
    "avatar_all_dimensions": [
      {
        "width": 100,
        "height": 100,
        "expires_at": 1788998400000,
        "image": "https://media.licdn.com/dms/image/.../shrink_100_100/..."
      }
    ],
    "background_picture_all_dimensions": [],
    "profile_pictures": [
      {
        "url": "https://media.licdn.com/dms/image/.../shrink_100_100/...",
        "width": 100,
        "height": 100
      }
    ],
    "background_pictures": [],
    "profile_headline": "VP of Engineering at Acme Corp",
    "description": "I lead the platform team at Acme.",
    "location": "Austin, Texas, United States",
    "country": "United States",
    "location_city": "Austin",
    "location_state": "Texas",
    "location_county": "",
    "address": null,
    "address_with_country": "Austin, Texas, United States",
    "address_without_country": "Austin, Texas",
    "address_country_only": "United States",
    "country_code": "US",
    "primary_locale": {
      "country": "US",
      "language": "en"
    },
    "is_creator": false,
    "is_premium": true,
    "is_influencer": false,
    "is_retired": false,
    "is_openlink": false,
    "is_job_seeker": false,
    "is_verified": false,
    "is_open_to_work": false,
    "is_hiring": false,
    "is_memorialized": null,
    "geo_location_backfilled": null,
    "show_premium_badge": null,
    "temp_status": null,
    "company_name_on_profile_top_card_shown": null,
    "education_on_profile_top_card_shown": null,
    "followers": 1280,
    "connections": 500,
    "job_title": "VP of Engineering",
    "raw_job_title": "VP of Engineering",
    "job_started_on": "3-2021",
    "job_ended_on": "",
    "job_still_working": true,
    "job_location": "Austin, Texas, United States",
    "job_location_city": "Austin",
    "job_location_state": "Texas",
    "job_location_county": "",
    "job_location_country": "United States",
    "job_description": [
      "Own the platform roadmap."
    ],
    "company_id": "1337",
    "company_image": "https://media.licdn.com/dms/image/...",
    "company_website": "https://acme.example",
    "company_industry": "Software Development",
    "industry": "Software Development",
    "industry_name": "Software Development",
    "industry_urn": "urn:li:fsd_industry:4",
    "current_company_name": "Acme Corp",
    "raw_company_name": "Acme Corp",
    "current_company_linkedin_url": "https://www.linkedin.com/company/acme-corp/",
    "total_experiences": 2,
    "experience": [
      {
        "job_title": "VP of Engineering",
        "company_id": "1337",
        "company_urn": "urn:li:fsd_company:1337",
        "company_username": "acme-corp",
        "company_url": "https://www.linkedin.com/company/acme-corp/",
        "company_name": "Acme Corp",
        "job_ended_on": "",
        "job_location": "Austin, Texas, United States",
        "company_image": "",
        "raw_job_title": "VP of Engineering",
        "job_started_on": "3-2021",
        "company_website": "",
        "employment_type": "Full-time",
        "job_description": [
          "Own the platform roadmap."
        ],
        "company_industry": "",
        "raw_company_name": "Acme Corp",
        "job_location_city": "Austin",
        "job_still_working": true,
        "job_location_state": "Texas",
        "job_location_county": "",
        "job_location_country": "United States",
        "company_headcount_range": "1,001-5,000 employees",
        "company_followers": "",
        "company_employee_count": "",
        "company_description": "",
        "workplace_type": "Hybrid",
        "skills": [
          "Distributed Systems",
          "Engineering Management"
        ],
        "position_urn": "urn:li:fsd_profilePosition:(ACoAAAExampleUrnNotARealMember,2122388595)",
        "geo_urn": "urn:li:fsd_geo:104994045",
        "total_duration": "5 yrs 7 mos",
        "position_group_urn": "urn:li:fsd_profilePositionGroup:(ACoAAAExampleUrnNotARealMember,0f1e2d3c4b5a69788796a5b4c3d2e1f001122334)",
        "position_group_id": "0f1e2d3c4b5a69788796a5b4c3d2e1f001122334",
        "geo_id": "104994045",
        "is_current": true
      }
    ],
    "education": [
      {
        "logo": "",
        "grade": "",
        "ended_on": {
          "year": 2009,
          "month": 0
        },
        "social_url": "",
        "started_on": {
          "year": 2005,
          "month": 0
        },
        "description": "",
        "university_id": "3223",
        "university_urn": "urn:li:fsd_company:3223",
        "university_website": "",
        "university_industry": "",
        "university_headcount_range": "",
        "university_followers": "",
        "university_employee_count": "",
        "university_description": "",
        "degree": "Bachelor of Science",
        "fields_of_study": [
          "Computer Science"
        ],
        "activities": "",
        "activities_inferred": false,
        "raw_text": "",
        "university_name": "University of Texas at Austin",
        "raw_university_name": "University of Texas at Austin",
        "education_urn": "urn:li:fsd_profileEducation:(ACoAAAExampleUrnNotARealMember,861262212)",
        "is_current": false,
        "skills": ""
      }
    ],
    "skills": [
      "Distributed Systems",
      "Engineering Management"
    ],
    "certification": [
      {
        "name": "AWS Certified Solutions Architect",
        "issuer": "Amazon Web Services (AWS)",
        "issuer_id": "",
        "issuer_urn": "",
        "issuer_url": "",
        "issuer_logo": "",
        "issued_on": {
          "month": 6,
          "year": 2022
        },
        "expires_on": {
          "month": 0,
          "year": 0
        },
        "credential_id": "ABC123",
        "credential_url": "",
        "description": "",
        "url": "",
        "authority": "Amazon Web Services (AWS)",
        "started_on": {
          "day": null,
          "year": 2022,
          "month": 6
        },
        "company_id": "",
        "end_date": {
          "day": 0,
          "month": 0,
          "year": 0
        },
        "company_logo": "",
        "company_name": "Amazon Web Services (AWS)"
      }
    ],
    "language": [
      {
        "name": "English",
        "proficiency": "NATIVE_OR_BILINGUAL"
      }
    ],
    "publication": [],
    "project": [],
    "volunteering": [],
    "honors_and_awards": [],
    "organizations": [],
    "patents": [],
    "courses": [],
    "same_name": [],
    "associated_hashtag": [
      "#engineering"
    ],
    "birthday": {
      "day": "",
      "year": "",
      "month": ""
    },
    "join_date": {
      "month": 4,
      "year": 2011
    },
    "causes": [
      "EDUCATION"
    ],
    "featured": [],
    "also_viewed": [
      {
        "entity_urn": "urn:li:fsd_profile:ACoAAB...",
        "first_name": "John",
        "last_name": "Smith",
        "headline": "CTO at Example",
        "public_identifier": "john-smith-example",
        "url": "https://linkedin.com/in/john-smith-example",
        "profile_picture": "https://media.licdn.com/dms/image/...",
        "follower_count": 897,
        "premium": true,
        "creator": false
      }
    ],
    "recommendations_received": [
      {
        "context": "John managed Jane directly",
        "date": "January 14, 2025",
        "description": "Jane is a great leader.",
        "name": "John Smith",
        "subtitle": "CTO at Example",
        "profile_picture_url": null,
        "url": "https://www.linkedin.com/in/john-smith-example",
        "urn": null,
        "last_modified_at": "2025-01-15T09:30:00.000Z"
      }
    ],
    "recommendations_given": [],
    "websites": [
      {
        "url": "https://janedoe.example",
        "category": "PERSONAL"
      }
    ],
    "contact_info": [],
    "updates": [],
    "creator_website": "",
    "geo_urn": "urn:li:fsd_geo:104994045",
    "connection_type": "OUT_OF_NETWORK",
    "entity_type": "Person",
    "current_school_id": "3223",
    "current_school_urn": "urn:li:fsd_school:3223",
    "is_top_voice": false,
    "show_follower_count": true,
    "test_scores": [
      {
        "name": "GMAT",
        "score": "730",
        "date": {
          "month": 6,
          "year": 2013
        }
      }
    ]
  }
}
```

## The person model

Every response carries **all** of the keys below, regardless of the profile. A value the profile does not have is an empty string (`""`), an empty array (`[]`) or `0` for the parts of a date; where a key can also be `null`, its type says so. Entries inside a list carry every key listed for that list.

Types are written as `string`, `number`, `boolean`, `object`, `array of strings`, `array of objects`. `X | null` means the key is `null` when the value is not available for the profile. That is different from an empty value: `followers: null` means the count could not be read, `followers: 0` means the profile has none.

### Properties

#### Basic information

**first\_name** `string`

First name.

**middle\_name** `string`

Middle name. Empty when none.

**last\_name** `string`

Last name.

**full\_name** `string`

Full name.

**display\_name** `string`

Name as displayed on LinkedIn.

**unformatted\_full\_name** `string`

Full name before any cleanup.

**pronoun** `string`

Pronouns the member set, e.g. `she/her`. Empty when not set.

**username** `string`

LinkedIn username (the vanity name in the profile URL).

**linkedin\_id** `string`

Numeric LinkedIn member ID, digits only. Derived from the profile URN.

**profile\_link** `string`

Profile URL, `https://linkedin.com/in/<username>`.

**sales\_id** `string`

LinkedIn profile URN, e.g. `urn:li:fsd_profile:ACoAA...`.

**linkedin\_sales\_link** `string`

Sales Navigator link to the profile.

**connection\_type** `string`

LinkedIn's network-distance label for the profile. In practice always `OUT_OF_NETWORK`, because requests are not made from a LinkedIn account connected to the member. Empty when not available for the profile.

**entity\_type** `string`

Type of the LinkedIn entity. In practice always `Person`. Empty when not available for the profile.

#### Headline and summary

**profile\_headline** `string`

Headline under the name.

**description** `string`

The About section.

#### Current role

**job\_title** `string`

Title of the current role.

**raw\_job\_title** `string`

Title exactly as shown on the profile.

**job\_description** `array of strings`

Description of the current role, one string per paragraph.

**job\_started\_on** `string`

Start of the current role as `M-YYYY`. A role dated by year only is `0-YYYY`. Empty when undated.

**job\_ended\_on** `string`

End of the role as `M-YYYY`. Empty while current.

**job\_still\_working** `boolean | null`

Whether the current role is still held. `null` when the role has neither a start nor an end date. `false` when the profile has no roles.

**job\_location** `string`

Location of the current role.

**job\_location\_city** `string`

City.

**job\_location\_state** `string`

State or region.

**job\_location\_county** `string`

County. Profiles do not show one, so this is empty.

**job\_location\_country** `string`

Country.

**total\_experiences** `number | null`

Number of roles on the profile. `null` when the total is not available for the profile.

#### Current company

**current\_company\_name** `string`

Employer in the current role.

**raw\_company\_name** `string`

Employer name exactly as shown.

**current\_company\_linkedin\_url** `string`

LinkedIn URL of the employer.

**company\_id** `string`

LinkedIn company ID of the employer.

**company\_image** `string`

Employer logo URL.

**company\_website** `string`

Employer website.

**company\_industry** `string`

Employer industry.

**industry** `string`

Industry the member lists on the profile.

**industry\_name** `string`

Same as `industry`.

**industry\_urn** `string`

LinkedIn URN of the industry.

#### Location

**location** `string`

Location as shown on the profile, e.g. `Austin, Texas, United States` or `Berlin Metropolitan Area`.

**country** `string`

Country name, e.g. `United States`.

**country\_code** `string`

Two-letter country code, e.g. `US`. Empty when not available.

**location\_city** `string`

City, or the metro area name.

**location\_state** `string`

State or region. Empty for a city-only or country-only location.

**location\_county** `string`

County. Profiles do not show one, so this is empty.

**address** `string | null`

Street address. Profiles do not show one, so this is `null`.

**address\_with\_country** `string`

Location with the country last.

**address\_without\_country** `string`

Location without the country.

**address\_country\_only** `string`

The country alone.

**geo\_urn** `string`

LinkedIn URN of the profile's location, e.g. `urn:li:fsd_geo:100495523`. Empty when not available for the profile.

**primary\_locale** `object`

The profile's language and country setting. `{}` when unknown.

**primary\_locale**

**country** `string`

Country code, e.g. `US`.

**language** `string`

Language code, e.g. `en`.

#### Contact information

**email** `string`

Email address, when publicly visible.

**phone\_number** `string | null`

Phone number. Phone numbers are not returned, so this is `null`.

**twitter\_link** `string`

Twitter / X profile link.

**websites** `array of objects`

Websites listed in the member's contact info. Empty when not available for the profile.

**websites**

**url** `string`

Link.

**category** `string`

LinkedIn's category: `PERSONAL`, `BLOG`, `PORTFOLIO`, `COMPANY`, `RSS`, `OTHER`, ... Empty when not stated.

**contact\_info** `array of objects`

Lines of the member's contact card. Empty when not available for the profile.

**contact\_info**

**title** `string`

Label, e.g. `Website`, `Phone`, `Email`.

**body** `string`

Its value.

**creator\_website** `string`

Website set in Creator mode. Empty when not a creator or none set.

#### Profile statistics

**connections** `number | null`

Number of connections. `null` when the count is not available for the profile, which is not the same as `0`.

**followers** `number | null`

Number of followers. `null` when the count is not available for the profile, which is not the same as `0`.

**join\_date** `object`

When the member joined LinkedIn. `0`s when not available for the profile.

**join\_date**

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

#### Profile attributes

**is\_premium** `boolean`

Has LinkedIn Premium.

**is\_creator** `boolean`

Is a LinkedIn creator.

**is\_influencer** `boolean`

Is a LinkedIn influencer.

**is\_job\_seeker** `boolean`

Is marked as a job seeker.

**is\_openlink** `boolean`

Uses OpenLink.

**is\_retired** `boolean`

Is retired.

**is\_verified** `boolean | null`

Has a verified badge. `null` when the provider that served this profile does not report verification at all, which is not a claim that the member is unverified.

**is\_open\_to\_work** `boolean | null`

Shows the Open to Work badge. `null` when the badge status is not available for the profile.

**is\_hiring** `boolean | null`

Shows the Hiring badge. `null` when the badge status is not available for the profile.

**is\_top\_voice** `boolean | null`

Has the LinkedIn Top Voice badge. `null` when not available for the profile.

**is\_memorialized** `boolean | null`

The profile is memorialized. `null` when not available for the profile.

**geo\_location\_backfilled** `boolean | null`

LinkedIn filled the location in itself. `null` when not available for the profile.

**show\_premium\_badge** `boolean | null`

The Premium badge is shown. `null` when not available for the profile.

**show\_follower\_count** `boolean | null`

The member shows their follower count publicly. `null` when not available for the profile.

**temp\_status** `null`

Reserved. Always `null`.

**company\_name\_on\_profile\_top\_card\_shown** `boolean | null`

Company name is shown on the top card. `null` when not available for the profile.

**education\_on\_profile\_top\_card\_shown** `boolean | null`

Education is shown on the top card. `null` when not available for the profile.

#### Profile media

**avatar\_url** `string`

Profile picture URL (largest size).

**background\_picture** `string`

Cover image URL.

**avatar\_all\_dimensions** `array of objects`

Profile picture at every size.

**avatar\_all\_dimensions**

**image** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**expires\_at** `number | null`

When the image URL expires, in milliseconds since the Unix epoch (read from the URL's `e=` parameter). `null` when the URL carries none.

**background\_picture\_all\_dimensions** `array of objects`

Cover image at every size.

**background\_picture\_all\_dimensions**

**image** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**expires\_at** `number | null`

When the image URL expires, in milliseconds since the Unix epoch (read from the URL's `e=` parameter). `null` when the URL carries none.

**profile\_pictures** `array of objects`

Profile picture at every size, without the expiry.

**profile\_pictures**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**background\_pictures** `array of objects`

Cover image at every size, without the expiry.

**background\_pictures**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

#### Personal details

**birthday** `object`

Birthday, when shared. Every part is an empty string when not shared.

**birthday**

**day** `string`

Day.

**month** `string`

Month.

**year** `string`

Year.

**causes** `array of strings`

Causes the member cares about, e.g. `ANIMAL_RIGHTS`. Empty when not available for the profile.

**associated\_hashtag** `array of strings`

Hashtags the member set in Creator mode. Empty when none.

#### Experience

**experience** `array of objects`

Work experience, newest first. Every entry carries all of these keys.

**experience**

**company\_name** `string`

Name of the company.

**raw\_company\_name** `string`

Company name exactly as shown on the profile.

**company\_url** `string`

LinkedIn URL of the company page.

**company\_id** `string`

LinkedIn company ID. Empty when the company has no LinkedIn page.

**company\_urn** `string`

LinkedIn company URN, e.g. `urn:li:fsd_company:1337`. Empty when there is no company ID.

**company\_username** `string`

Company's LinkedIn universal name (the slug in its page URL).

**company\_image** `string`

Company logo URL.

**company\_industry** `string`

Industry of the company, when we have company data for it.

**company\_website** `string`

Company website, when we have company data for it.

**company\_headcount\_range** `string`

Company size band, e.g. `1,001-5,000 employees`. Empty when unknown.

**company\_followers** `string`

Followers of the company page, when we have company data for it.

**company\_employee\_count** `string`

Employee count, when we have company data for it.

**company\_description** `string`

Company description, when we have company data for it.

**job\_title** `string`

Job title.

**raw\_job\_title** `string`

Job title exactly as shown on the profile.

**employment\_type** `string`

LinkedIn's employment type, e.g. `Full-time`, `Part-time`, `Contract`, `Self-employed`, `Freelance`, `Internship`. Empty when the profile shows none.

**workplace\_type** `string`

`On-site`, `Remote` or `Hybrid`. Empty when unknown.

**skills** `array of strings`

Skills attached to this role. Empty when not available for the profile.

**position\_urn** `string`

LinkedIn URN of this position, e.g. `urn:li:fsd_profilePosition:(ACoAAA...,2122388595)`. Empty when not available for the profile.

**geo\_urn** `string`

LinkedIn URN of the role's location, e.g. `urn:li:fsd_geo:90009761`. Empty when not available for the profile.

**total\_duration** `string`

Length of the role as LinkedIn words it, e.g. `4 yrs 10 mos`. Empty when not available for the profile.

**job\_description** `array of strings`

Role description, one string per paragraph.

**job\_location** `string`

Location of the role as shown on the profile. Falls back to the profile's own location when the role shows none.

**job\_location\_city** `string`

City of the role.

**job\_location\_state** `string`

State or region of the role.

**job\_location\_county** `string`

County of the role. Profiles do not show one, so this is empty.

**job\_location\_country** `string`

Country of the role.

**job\_started\_on** `string`

Start date as `M-YYYY`, e.g. `3-2021`. A role dated by year only is `0-YYYY`. Empty when the role has no date.

**job\_ended\_on** `string`

End date as `M-YYYY`. Empty for a current role or when the role has no date.

**job\_still\_working** `boolean | null`

Whether this is a current role. `null` when the role has neither a start nor an end date, so it is not known.

**position\_group\_urn** `string`

LinkedIn URN that groups the roles held at one company, e.g. `urn:li:fsd_profilePositionGroup:(ACoAAA...,fd67192250d4aaf2095f46be4b3b42dd1e363727)`. Roles with the same value are at the same company. Empty when not available for the profile.

**position\_group\_id** `string`

The identifier inside `position_group_urn`. Empty when not available for the profile.

**geo\_id** `string`

The number inside `geo_urn`, e.g. `90009761`. Empty when not available for the profile.

**is\_current** `boolean | null`

LinkedIn's own current-role flag. `null` when not available for the profile.

#### Education

**education** `array of objects`

Education entries. Every entry carries all of these keys.

**education**

**university\_name** `string`

Name of the school.

**raw\_university\_name** `string`

School name exactly as shown on the profile.

**university\_id** `string`

LinkedIn school ID.

**university\_urn** `string`

LinkedIn school URN.

**social\_url** `string`

LinkedIn URL of the school page.

**logo** `string`

School logo URL.

**university\_website** `string`

School website, when we have company data for it.

**university\_industry** `string`

Industry of the school, when we have company data for it.

**university\_headcount\_range** `string`

School size band, when we have company data for it.

**university\_followers** `string`

Followers of the school page, when we have company data for it.

**university\_employee\_count** `string`

Employee count, when we have company data for it.

**university\_description** `string`

School description, when we have company data for it.

**degree** `string`

Degree, e.g. `Bachelor of Science`.

**fields\_of\_study** `array of strings`

Fields of study.

**grade** `string`

Grade.

**activities** `string`

Activities and societies.

**activities\_inferred** `boolean`

`true` when `activities` was recovered from the description rather than sent as its own field.

**description** `string`

Description of the education entry.

**started\_on** `object`

Start date.

**started\_on**

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**ended\_on** `object`

End date, or expected end date.

**ended\_on**

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**raw\_text** `string`

The unsplit original line exactly as it appears on the profile.

**education\_urn** `string`

LinkedIn URN of this education entry, e.g. `urn:li:fsd_profileEducation:(ACoAAA...,861262212)`. Empty when not available for the profile.

**is\_current** `boolean | null`

LinkedIn's own current flag for the entry. `null` when not available for the profile.

**skills** `string`

The skills line LinkedIn shows under the entry, as text, e.g. `Optimal Control, Simulink and +3 skills`. It is not a complete list. Empty when not available for the profile.

**current\_school\_id** `string`

LinkedIn ID of the school of the profile's top education. Empty when not available for the profile.

**current\_school\_urn** `string`

LinkedIn URN of that school, e.g. `urn:li:fsd_school:12260`. Empty when not available for the profile.

#### Skills, languages and credentials

**skills** `array of strings`

Skill names.

**language** `array of objects`

Languages.

**language**

**name** `string`

Language name.

**proficiency** `string`

One of `ELEMENTARY`, `LIMITED_WORKING`, `PROFESSIONAL_WORKING`, `FULL_PROFESSIONAL`, `NATIVE_OR_BILINGUAL`. Empty when not stated.

**certification** `array of objects`

Licenses and certifications.

**certification**

**name** `string`

Certification name.

**issuer** `string`

Issuing organization.

**issuer\_id** `string`

LinkedIn ID of the issuer.

**issuer\_urn** `string`

LinkedIn URN of the issuer.

**issuer\_url** `string`

LinkedIn page of the issuer.

**issuer\_logo** `string`

Issuer logo URL.

**issued\_on** `object`

Issue date.

**issued\_on**

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**expires\_on** `object`

Expiry date. `0`s when the certification does not expire.

**expires\_on**

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**credential\_id** `string`

Credential ID.

**credential\_url** `string`

Credential URL.

**description** `string`

Description.

**url** `string`

Same as `credential_url`.

**authority** `string`

Same as `issuer`.

**started\_on** `object`

Same date as `issued_on`; `month` and `year` are `null` when unknown.

**started\_on**

**day** `null`

Always `null`.

**month** `number | null`

Month.

**year** `number | null`

Year.

**company\_id** `string`

Same as `issuer_id`.

**company\_name** `string`

Same as `issuer`.

**company\_logo** `string`

Same as `issuer_logo`.

**end\_date** `object`

Same date as `expires_on`, with a `day`.

**end\_date**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**honors\_and\_awards** `array of objects`

Honors and awards.

**honors\_and\_awards**

**title** `string`

Title of the honor or award.

**issuer** `string`

Issuer.

**description** `string`

Description.

**issued\_on** `object`

Date issued.

**issued\_on**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**honor\_urn** `string`

LinkedIn URN of this honor, e.g. `urn:li:fsd_profileHonor:(ACoAAA...,298568186)`. Empty when not available for the profile.

**position\_urn** `string`

LinkedIn URN of the role this entry is attached to, matching `position_urn` on an `experience` entry. Empty when not available for the profile.

**education\_urn** `string`

LinkedIn URN of the education entry this is attached to, matching `education_urn` on an `education` entry. Empty when not available for the profile.

**organizations** `array of objects`

Organization memberships.

**organizations**

**title** `string`

Organization name.

**name** `string`

Same as `title`.

**subtitle** `string`

Position held.

**position\_held** `string`

Same as `subtitle`.

**description** `string`

Description.

**start** `object`

Start date.

**start**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**end** `object`

End date. `0`s when ongoing or unknown.

**end**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**organization\_urn** `string`

LinkedIn URN of this organization entry, e.g. `urn:li:fsd_profileOrganization:(ACoAAA...,894021540)`. Empty when not available for the profile.

**position\_urn** `string`

LinkedIn URN of the role this entry is attached to, matching `position_urn` on an `experience` entry. Empty when not available for the profile.

**education\_urn** `string`

LinkedIn URN of the education entry this is attached to, matching `education_urn` on an `education` entry. Empty when not available for the profile.

**courses** `array of objects`

Courses.

**courses**

**name** `string`

Course name.

**number** `string`

Course number.

**course\_urn** `string`

LinkedIn URN of this course, e.g. `urn:li:fsd_profileCourse:(ACoAAA...,1703125625)`. Empty when not available for the profile.

**position\_urn** `string`

LinkedIn URN of the role this entry is attached to, matching `position_urn` on an `experience` entry. Empty when not available for the profile.

**education\_urn** `string`

LinkedIn URN of the education entry this is attached to, matching `education_urn` on an `education` entry. Empty when not available for the profile.

**test\_scores** `array of objects`

Test scores listed on the profile. Empty when none.

**test\_scores**

**name** `string`

Test name.

**score** `string`

Score as shown, e.g. `113`.

**date** `object`

Date of the test.

**date**

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

#### Work outside employment

**volunteering** `array of objects`

Volunteer experience.

**volunteering**

**role** `string`

Role.

**organization** `string`

Organization name.

**company\_name** `string`

Same as `organization`.

**company\_id** `string`

LinkedIn company ID.

**company\_url** `string`

LinkedIn company page.

**company\_image** `string`

Organization logo URL.

**company\_logo** `string`

Same as `company_image`.

**cause** `string`

Cause, e.g. `HEALTH`.

**description** `string`

Description.

**started\_on** `string`

Start as `M-YYYY`. Empty when unknown.

**ended\_on** `string`

End as `M-YYYY`. Empty when current or unknown.

**start\_date** `object`

Start date.

**start\_date**

**year** `number`

Year. `0` when unknown.

**month** `number`

Month. `0` when unknown.

**end\_date** `object`

End date.

**end\_date**

**year** `number`

Year. `0` when unknown.

**month** `number`

Month. `0` when unknown.

**is\_current\_position** `boolean`

`true` when there is a start date and no end date. An undated entry is `false`.

**duration** `object`

Length of the entry, to today when it is current.

**duration**

**years** `number`

Whole years.

**months** `number`

Remaining months.

**volunteer\_experience\_urn** `string`

LinkedIn URN of this volunteer entry, e.g. `urn:li:fsd_profileVolunteerExperience:(ACoAAA...,1621785864)`. Empty when not available for the profile.

**publication** `array of objects`

Publications.

**publication**

**name** `string`

Title.

**publisher** `string`

Publisher.

**description** `string`

Description.

**url** `string`

Link to the publication.

**published\_on** `string`

Date as `M/D/YYYY` (`M//YYYY` when the day is unknown). Empty when unknown.

**published\_on\_date** `object`

The same date as an object.

**published\_on\_date**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**publishing\_date** `string`

The same date as text, e.g. `Mar 4 2021`.

**authors** `array of objects`

Co-authors.

**authors**

**url** `string`

LinkedIn profile URL.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**headline** `string`

Profile headline.

**public\_identifier** `string`

LinkedIn username (vanity name).

**urn** `string`

LinkedIn profile URN.

**profile\_picture\_url** `string`

Profile picture URL.

**publication\_urn** `string`

LinkedIn URN of this publication, e.g. `urn:li:fsd_profilePublication:(ACoAAA...,1798667697)`. Empty when not available for the profile.

**patents** `array of objects`

Patents.

**patents**

**title** `string`

Patent title.

**subtitle** `string`

Patent number and issue date as LinkedIn shows them.

**description** `string`

Description.

**url** `string`

Link to the patent.

**patent\_number** `string`

Patent number.

**application\_number** `string`

Application number.

**issuer** `string`

Patent office.

**pending** `boolean`

`true` for a pending patent.

**filed\_on** `object`

Filing date.

**filed\_on**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**issued\_on** `object`

Issue date.

**issued\_on**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**inventors** `array of objects`

Inventors.

**inventors**

**url** `string`

LinkedIn profile URL.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**headline** `string`

Profile headline.

**public\_identifier** `string`

LinkedIn username (vanity name).

**urn** `string`

LinkedIn profile URN.

**profile\_picture\_url** `string`

Profile picture URL.

**patent\_urn** `string`

LinkedIn URN of this patent, e.g. `urn:li:fsd_profilePatent:(ACoAAA...,377)`. Empty when not available for the profile.

**project** `array of objects`

Projects.

**project**

**title** `string`

Project title.

**subtitle** `string`

Date line as shown on the profile, e.g. `May 2015 - Present`.

**description** `string`

Description.

**date** `string`

Dates as `M-YYYY - M-YYYY`.

**associated\_with** `string`

The school or role the project is associated with.

**url** `string`

Project link.

**start** `object`

Start date.

**start**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**end** `object`

End date. `0`s when ongoing or unknown.

**end**

**day** `number`

Day. `0` when unknown.

**month** `number`

Month, `1`-`12`. `0` when unknown.

**year** `number`

Year. `0` when unknown.

**contributors** `array of objects`

Other contributors.

**contributors**

**url** `string`

LinkedIn profile URL.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**headline** `string`

Profile headline.

**public\_identifier** `string`

LinkedIn username (vanity name).

**urn** `string`

LinkedIn profile URN.

**profile\_picture\_url** `string`

Profile picture URL.

**project\_urn** `string`

LinkedIn URN of this project, e.g. `urn:li:fsd_profileProject:(ACoAAA...,109)`. Empty when not available for the profile.

**position\_urn** `string`

LinkedIn URN of the role this entry is attached to, matching `position_urn` on an `experience` entry. Empty when not available for the profile.

**education\_urn** `string`

LinkedIn URN of the education entry this is attached to, matching `education_urn` on an `education` entry. Empty when not available for the profile.

**featured** `array of objects`

Items pinned to the Featured section. Empty when not available for the profile.

**featured**

**type** `string`

Kind of item, e.g. `post`, `article`, `link`, `media`.

**title** `string`

Title.

**description** `string`

Description.

**url** `string`

Link.

**image\_url** `string`

Image URL.

**date** `string`

Date text shown on the item, when it has one.

**social\_counts** `object`

Engagement on the item.

**social\_counts**

**likes** `number | null`

Likes. `null` when not available for the item.

**comments** `number | null`

Comments. `null` when not available for the item.

**reaction\_counts** `array of objects`

Counts per reaction type.

**reaction\_counts**

**type** `string`

Reaction type, e.g. `LIKE`.

**count** `number`

Count.

#### Recommendations

**recommendations\_received** `array of objects`

Recommendations the member received. Empty when not available for the profile.

**recommendations\_received**

**name** `string | null`

Name of the other person: the author of a received recommendation, the recipient of a given one.

**subtitle** `string | null`

That person's headline.

**url** `string | null`

That person's LinkedIn profile URL.

**urn** `string | null`

That person's LinkedIn profile URN.

**profile\_picture\_url** `string | null`

That person's picture URL.

**description** `string | null`

Text of the recommendation.

**date** `string | null`

Date, e.g. `January 14, 2025`.

**context** `string | null`

LinkedIn's relationship line, e.g. `Ryan managed Peter directly`.

**last\_modified\_at** `string | null`

When the recommendation was last edited, as an ISO 8601 timestamp, e.g. `2022-12-15T19:26:33.377Z`. `null` when not available for the profile.

**recommendations\_given** `array of objects`

Recommendations the member gave. Empty when not available for the profile.

**recommendations\_given**

**name** `string | null`

Name of the other person: the author of a received recommendation, the recipient of a given one.

**subtitle** `string | null`

That person's headline.

**url** `string | null`

That person's LinkedIn profile URL.

**urn** `string | null`

That person's LinkedIn profile URN.

**profile\_picture\_url** `string | null`

That person's picture URL.

**description** `string | null`

Text of the recommendation.

**date** `string | null`

Date, e.g. `January 14, 2025`.

**context** `string | null`

LinkedIn's relationship line, e.g. `Ryan managed Peter directly`.

**last\_modified\_at** `string | null`

When the recommendation was last edited, as an ISO 8601 timestamp, e.g. `2022-12-15T19:26:33.377Z`. `null` when not available for the profile.

#### Related profiles and activity

**also\_viewed** `array of objects`

Profiles viewers also viewed. Empty when not available for the profile.

**also\_viewed**

**entity\_urn** `string`

LinkedIn profile URN.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**headline** `string`

Headline.

**public\_identifier** `string`

LinkedIn username.

**url** `string`

Profile URL.

**profile\_picture** `string`

Picture URL.

**follower\_count** `number | null`

Followers. `null` when not known.

**premium** `boolean | null`

Premium member. `null` when not known.

**creator** `boolean | null`

Creator. `null` when not known.

**same\_name** `array`

Reserved. Always an empty array.

**updates** `array of objects`

The member's recent posts, Empty when not available for the profile. For posts use the person activity endpoint.

**updates**

**urn** `string`

Post URN.

**post\_link** `string`

Post URL.

**post\_text** `string`

Post text.

**posted\_at** `string`

When it was posted.

**posted\_ago** `string`

Relative time, e.g. `2w`.

**is\_repost** `boolean`

Whether it is a repost.

**links\_in\_post** `array`

Links found in the post.

**num\_likes** `number`

Likes.

**num\_comments** `number`

Comments.

**num\_shares** `number`

Shares.

**reaction\_counts** `array`

Counts per reaction type.

**image** `array`

Images in the post.

**video\_thumbnail** `string`

Video thumbnail URL.

**video\_duration\_ms** `number`

Video length in milliseconds.

**article** `object`

Linked article details.

#### Enrichment fields

These fields are only present when the matching [enrichment flag](#enrichment-flags) was set to `true` on the request. On failure the field contains `{ "error": "Unable to fetch this data at this time." }` instead of data, and no extra credit is charged.

**company\_interest** `object`

Present when `company_interest` is requested. Companies the profile follows.

**Company interest object**

**items** `array of objects`

Followed companies.

**items**

**id** `number`

LinkedIn company ID.

**name** `string`

Company name.

**linkedin\_url** `string`

LinkedIn company page URL.

**logo** `array of objects`

Company logo at different sizes. Empty when there is none.

**logo**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**staff\_count\_range** `object`

Employee headcount range, `{}` when not available.

**total** `number`

Total number of followed companies.

**total\_pages** `number`

Total number of pages available.

**current\_page** `number`

Page returned in this response.

**top\_voices\_interest** `object`

Present when `top_voices_interest` is requested. LinkedIn Top Voices the profile follows. This one is not paginated.

**Top voices interest object**

**items** `array of objects | null`

Followed Top Voices, or `null` when the profile follows none.

**items**

**urn** `string`

LinkedIn profile URN (without the `urn:li:fsd_profile:` prefix).

**username** `string`

LinkedIn username.

**url** `string`

LinkedIn profile URL.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**full\_name** `string`

Full name.

**headline** `string`

Profile headline.

**profile\_picture** `array of objects`

Profile picture at different sizes. Empty when there is none.

**profile\_picture**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**group\_interest** `object`

Present when `group_interest` is requested. LinkedIn Groups the profile belongs to.

**Group interest object**

**items** `array of objects | null`

Joined groups, or `null` when the profile has no group memberships.

**items**

**entity\_urn** `string`

LinkedIn group URN, e.g. `urn:li:fsd_group:14780171`.

**name** `string`

Group name.

**url** `string`

LinkedIn group URL.

**member\_count** `number`

Number of members.

**logo** `array of objects`

Group logo at different sizes. Empty when there is none.

**logo**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**total** `number`

Total number of joined groups.

**total\_pages** `number`

Total number of pages available.

**current\_page** `number`

Page returned in this response.

**school\_interest** `object`

Present when `school_interest` is requested. Schools the profile follows.

**School interest object**

**items** `array of objects | null`

Followed schools, or `null` when the profile follows none.

**items**

**id** `number`

LinkedIn school ID.

**name** `string`

School name.

**url** `string`

LinkedIn school page URL.

**follower\_count** `number`

Number of followers the school page has.

**logo** `array of objects`

School logo at different sizes. Empty when there is none.

**logo**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**total** `number`

Total number of followed schools.

**total\_pages** `number`

Total number of pages available.

**current\_page** `number`

Page returned in this response.

**newsletter\_interest** `object`

Present when `newsletter_interest` is requested. LinkedIn Newsletters the profile is subscribed to.

**Newsletter interest object**

**items** `array of objects`

Subscribed newsletters.

**items**

**name** `string`

Newsletter name.

**url** `string`

LinkedIn newsletter URL.

**description** `string`

Newsletter description.

**publication\_frequency** `string`

How often it is published, e.g. `Published weekly`.

**logo** `array of objects`

Newsletter logo at different sizes. Empty when there is none.

**logo**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**publisher** `object`

Who publishes the newsletter. `first_name`, `last_name`, `username`, `urn` and `profile_picture` are present when the publisher is a person.

**publisher**

**full\_name** `string`

Publisher name.

**url** `string`

LinkedIn URL of the publisher.

**first\_name** `string`

First name.

**last\_name** `string`

Last name.

**username** `string`

LinkedIn username.

**urn** `string`

LinkedIn profile URN (without the `urn:li:fsd_profile:` prefix).

**profile\_picture** `array of objects`

Publisher picture at different sizes.

**profile\_picture**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**total** `number`

Total number of subscribed newsletters.

**total\_pages** `number`

Total number of pages available.

**current\_page** `number`

Page returned in this response.

**similar\_profiles** `array of objects`

Present when `similar_profiles` is requested. Profiles similar to this one, as a plain list. Every entry carries all six keys; a value that is not available is an empty string. The list is empty when there are no similar profiles.

**Similar profile item**

**name** `string`

Full name.

**url** `string`

LinkedIn profile URL.

**headline** `string`

Profile headline.

**location** `string`

Location, when available.

**profile\_picture** `string`

URL of the largest profile picture.

**urn** `string`

LinkedIn profile URN, e.g. `urn:li:fsd_profile:ACoAAA...`.

**recommendations\_data** `object`

Present when `recommendations_data` is requested. The recommendations this person gave and received.

**Recommendations data object**

**given\_recommendation\_count** `number`

Total number of recommendations this person has given. Can be larger than the number of entries returned.

**given\_recommendation** `array of objects`

Recommendations this person gave.

**given\_recommendation**

**text** `string`

Text of the recommendation.

**created** `number`

When it was written, in milliseconds since the Unix epoch.

**last\_modified** `number`

When it was last edited, in milliseconds since the Unix epoch.

**relationship** `string`

How the two people know each other. One of `WORKED_IN_SAME_GROUP`, `WORKED_IN_DIFFERENT_GROUPS`, `WORKED_IN_DIFFERENT_COMPANIES`, `RECOMMENDER_MANAGED_RECOMMENDEE`, `RECOMMENDER_REPORTED_TO_RECOMMENDEE`, `RECOMMENDER_SENIOR_THAN_RECOMMENDEE`, `RECOMMENDEE_SENIOR_THAN_RECOMMENDER`, `RECOMMENDER_ADVISED_RECOMMENDEE`, `RECOMMENDER_TAUGHT_RECOMMENDEE`, `RECOMMENDER_STUDIED_WITH_RECOMMENDEE`, `RECOMMENDER_IS_CLIENT_OF_RECOMMENDEE`, `RECOMMENDEE_IS_CLIENT_OF_RECOMMENDER`, `NONE`.

**recommendee** `object`

The person who received it.

**recommendee**

**first\_name** `string`

First name of the recommendee (may include a middle name).

**last\_name** `string`

Last name.

**occupation** `string`

Their headline.

**username** `string`

LinkedIn username.

**profile\_pictures** `array of objects`

Picture at different sizes. Empty when there is none.

**profile\_pictures**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.

**received\_recommendation\_count** `number`

Total number of recommendations this person has received. Can be larger than the number of entries returned.

**received\_recommendation** `array of objects`

Recommendations this person received.

**received\_recommendation**

**text** `string`

Text of the recommendation.

**created** `number`

When it was written, in milliseconds since the Unix epoch.

**last\_modified** `number`

When it was last edited, in milliseconds since the Unix epoch.

**relationship** `string`

How the two people know each other. One of `WORKED_IN_SAME_GROUP`, `WORKED_IN_DIFFERENT_GROUPS`, `WORKED_IN_DIFFERENT_COMPANIES`, `RECOMMENDER_MANAGED_RECOMMENDEE`, `RECOMMENDER_REPORTED_TO_RECOMMENDEE`, `RECOMMENDER_SENIOR_THAN_RECOMMENDEE`, `RECOMMENDEE_SENIOR_THAN_RECOMMENDER`, `RECOMMENDER_ADVISED_RECOMMENDEE`, `RECOMMENDER_TAUGHT_RECOMMENDEE`, `RECOMMENDER_STUDIED_WITH_RECOMMENDEE`, `RECOMMENDER_IS_CLIENT_OF_RECOMMENDEE`, `RECOMMENDEE_IS_CLIENT_OF_RECOMMENDER`, `NONE`.

**recommender** `object`

The author.

**recommender**

**first\_name** `string`

First name of the recommender (may include a middle name).

**last\_name** `string`

Last name.

**occupation** `string`

Their headline.

**username** `string`

LinkedIn username.

**profile\_pictures** `array of objects`

Picture at different sizes. Empty when there is none.

**profile\_pictures**

**url** `string`

Image URL.

**width** `number`

Width in pixels.

**height** `number`

Height in pixels.


# Person Activity
Source: https://docs.datamagnet.co/api-reference/endpoints/people-activity

POST https://api.datamagnet.co/api/v1/person/activity
Retrieve a LinkedIn member's recent activity by profile URL, including posts, comments, likes, and shares for engagement monitoring workflows.

# Person Activity

**Cost:** `10` credits / successful request. A profile that does not exist is answered `"message": "Person does not exist."`, `"error_code": "profile_not_found"`, `"retryable": false`, and is charged like a successful request; a lookup that fails for a temporary reason is not charged.

This endpoint retrieves the recent activity of a LinkedIn person profile based on the provided LinkedIn URL. The response includes details about the person's posts, including text, attachments, reactions, and more.

## Person activity endpoint

This endpoint allows you to get structured data of a LinkedIn Person Profile's activity.

### Required attributes

**url** `string` *required*

The LinkedIn profile URL of the person whose activity you want to retrieve.

### Optional attributes

**type** `string`

Alters the type of posts to be fetched.

* `posts` The default behavior. Fetches all posts and reposts for the profile.
* `comments` - Fetch only posts which the profile commented on.
* `reactions` - Fetch only posts which the profile reacted to.
* `articles` - Fetch only articles posted by the profile.

**cursor** `string`

Use this parameter to paginate through results. Use the cursor returned from your previous request.

### Response

```json Response theme={null}
{
  "cursor": "eyJjb3VudCI6MTAwLCJzdGFydCI6MTAwLCJwYWdpbmF0aW9uVG9rZW4i...",
  "message": [
    {
      "activity_type": "Post",
      "attachments": null,
      "author": {
        "image_url": "https://media.licdn.com/dms/image/...",
        "occupation": "Head of Talent, Anthropic",
        "public_identifier": "gouldjames",
        "title": "Jimmy Gould",
        "type": "Member",
        "url": "https://linkedin.com/in/gouldjames",
        "urn": "urn:li:fsd_profile:ACoAAAANoqwBhs9WE_vNa9Ias3JiEUUO0F4iTDk"
      },
      "comments": 0,
      "created_at": "2025-12-05T22:37:37.579Z",
      "is_repost": false,
      "likes": 110,
      "mentions": [
        {
          "entity_urn": "urn:li:fsd_profile:ACoAAAXCzi8BikDXxPm2lUfNvihMqKmhvKGmrpw"
        }
      ],
      "reactions": [
        { "count": 73, "reaction_type": "LIKE" },
        { "count": 23, "reaction_type": "EMPATHY" },
        { "count": 9, "reaction_type": "INTEREST" }
      ],
      "share_url": "https://www.linkedin.com/posts/gouldjames_...",
      "shared_post": {
        "attachments": [
          {
            "subtitle": "anthropic.com",
            "title": "Guidance on Candidates' AI Usage",
            "type": "Article",
            "url": "https://www.anthropic.com/candidate-ai-guidance",
            "urn": "urn:li:article:7340433422727031236"
          }
        ],
        "author": {
          "image_url": "https://media.licdn.com/dms/image/...",
          "occupation": "Data-Driven Recruiting...",
          "public_identifier": "alison-bunnell",
          "title": "Alison Bunnell",
          "type": "Member",
          "url": "https://linkedin.com/in/alison-bunnell",
          "urn": "urn:li:fsd_profile:..."
        },
        "comments": 30,
        "created_at": "2025-12-05T18:11:00.510Z",
        "is_repost": false,
        "likes": 714,
        "reactions": [
          { "count": 564, "reaction_type": "LIKE" },
          { "count": 76, "reaction_type": "EMPATHY" }
        ],
        "share_url": "https://www.linkedin.com/posts/alison-bunnell_...",
        "shared_post": null,
        "shares": 29,
        "text": "An inside scoop from an Anthropic recruiter's perspective...",
        "url": "https://www.linkedin.com/feed/update/...",
        "urn": "urn:li:activity:7402771491890597888"
      },
      "shares": 0,
      "text": "Some great words from Alison Bunnell - she's absolutely right!",
      "url": "https://www.linkedin.com/feed/update/urn:li:activity:7402838588461125632",
      "urn": "urn:li:activity:7402838588461125632"
    },
    {
      "activity_type": "Repost",
      "shared_post": {
        "attachments": [
          {
            "navigation_context": {
              "action_target": "https://www.cbsnews.com/video/..."
            },
            "title": "Anthropic knows AI comes with risks...",
            "type": "ExternalVideo",
            "urn": "urn:li:article:9179999911804862012",
            "website": "cbsnews.com"
          }
        ],
        "author": {
          "image_url": "https://media.licdn.com/dms/image/...",
          "occupation": "Chief Communications Officer, Anthropic",
          "public_identifier": "sashademarigny",
          "title": "Sasha de Marigny",
          "type": "Member",
          "url": "https://linkedin.com/in/sashademarigny",
          "urn": "urn:li:fsd_profile:..."
        },
        "comments": 12,
        "created_at": "2025-11-17T12:25:07.148Z",
        "is_repost": false,
        "likes": 502,
        "mentions": [],
        "reactions": [
          { "count": 387, "reaction_type": "LIKE" },
          { "count": 45, "reaction_type": "EMPATHY" }
        ],
        "share_url": "https://www.linkedin.com/posts/sashademarigny_...",
        "shared_post": null,
        "shares": 29,
        "text": "AI has the potential to compress a century...",
        "url": "https://www.linkedin.com/feed/update/...",
        "urn": "urn:li:activity:7396021973555924992"
      }
    }
  ]
}
```

## The person activity model

This contains the structured data of a person's recent activity on LinkedIn.

### Properties

**cursor** `string`

Pagination token for fetching more activities. Use this in the next request to get the next page. The cursor stays set until the page after the last item, so keep requesting until a page comes back empty or without a cursor. That final empty page is not charged. Page size varies, up to about 100, and a short page can appear in the middle of a list, so the number of items does not tell you a page is the last one.

**message** `array`

List of activity items (posts, comments, reactions, articles).

**Activity object**

#### Activity Details

**activity\_type** `string`

Type of activity: "Post" or "Repost". When "Repost", the activity only contains a `shared_post` object.

**text** `string`

Text content of the activity (only present for "Post" activity\_type).

**url** `string`

LinkedIn URL of the activity (only present for "Post" activity\_type).

**urn** `string`

Unique LinkedIn URN identifier for the activity (only present for "Post" activity\_type).

**created\_at** `string`

ISO 8601 timestamp when the activity was created (only present for "Post" activity\_type).

**share\_url** `string`

Direct shareable URL for the activity (only present for "Post" activity\_type).

#### Activity Type

**is\_repost** `boolean`

Whether this activity is a repost/share (only present for "Post" activity\_type).

#### Activity Author (For "Post" type only)

**author** `object`

Details about the activity author (only present for "Post" activity\_type).

**Author object**

**title** `string`

Author's name.

**occupation** `string`

Author's LinkedIn headline.

**public\_identifier** `string`

Author's LinkedIn username.

**type** `string`

Author type ("Member" or "Company").

**url** `string`

LinkedIn profile/page URL.

**image\_url** `string`

Profile picture URL.

**logo** `string`

Company logo URL (for Company type).

**urn** `string`

Author's URN identifier.

#### Attachments (For "Post" type only)

**attachments** `array`

List of media attachments (only present for "Post" activity\_type, can be null).

**Attachment object**

**type** `string`

Type of attachment: "Article", "Video", "ExternalVideo", "Image", "Document", etc.

**url** `string`

URL of the attachment or article.

**title** `string`

Title of the attachment.

**subtitle** `string`

Subtitle or source.

**text** `string`

Description or caption.

**urn** `string`

Attachment URN identifier.

**duration** `number`

Video duration in milliseconds (for Video type).

**website** `string`

Website domain (for ExternalVideo/Article types).

**navigation\_context** `object`

Navigation context with action\_target URL (for ExternalVideo type).

#### Engagement Metrics (For "Post" type only)

**likes** `number`

Total number of likes/reactions (only present for "Post" activity\_type).

**comments** `number`

Number of comments (only present for "Post" activity\_type).

**shares** `number`

Number of shares/reposts (only present for "Post" activity\_type).

**reactions** `array`

Breakdown of reactions by type (only present for "Post" activity\_type).

**Reaction object**

**count** `number`

Number of this reaction type.

**reaction\_type** `string`

Type of reaction: "LIKE", "PRAISE", "EMPATHY", "INTEREST", "APPRECIATION", "ENTERTAINMENT", "MAYBE", "FUNNY".

#### Mentions & Shares (For "Post" type only)

**mentions** `array`

List of @mentioned users/companies in the activity (only present for "Post" activity\_type).

**Mention object**

**entity\_urn** `string`

URN of the mentioned profile/company.

**name** `string`

Name of the mentioned entity (when available).

#### Comment mentions (For "Comment" and "Reply" types)

**comment** `object`

The comment itself. Its `mentions` array lists the people and companies tagged in the comment text, with the same fields as a post mention plus `type` (`"profileMention"` or `"companyMention"`). The top-level `mentions` on these items describes the post, not the comment.

**shared\_post** `object`

Details of the shared/reposted content. For "Post" activity\_type, this field is optional and contains details if the post is sharing another post. For "Repost" activity\_type, this is the only content field present.

**Shared post object**

**attachments** `array`

Attachments from the original post.

**author** `object`

Original post author information.

**text** `string`

Original post text content.

**url** `string`

Original post URL.

**urn** `string`

Original post URN.

**created\_at** `string`

When the original post was created.

**likes** `number`

Original post likes count.

**comments** `number`

Original post comments count.

**shares** `number`

Original post shares count.

**reactions** `array`

Original post reactions breakdown.

**share\_url** `string`

Original post shareable URL.

**shared\_post** `object`

Nested shared post (if the original was also a share).

**is\_repost** `boolean`

Whether the original post was a repost.

**mentions** `array`

Mentions in the original post.


# People Search DB
Source: https://docs.datamagnet.co/api-reference/endpoints/people-db-search

POST https://api.datamagnet.co/api/v1/people/search/db
Search Datamagnet's own database of previously enriched LinkedIn profiles by keyword, location, company, job title, and more — with include/exclude support for company LinkedIn URLs.

# People Search DB

**Cost:** `10` credits/search.

Search Datamagnet's internal database of already-enriched LinkedIn profiles. Unlike [ICP People Search](/api-reference/endpoints/icp-people-search), which queries LinkedIn live, this endpoint searches previously collected profile records — so it returns instantly and doesn't use live-lookup capacity. Each page returns up to `50` results. For companies rather than people, see [Company Search DB](/api-reference/endpoints/company-db-search).

## People search DB endpoint

Most filter fields accept multiple values. Values within the same field are OR'd together (e.g. `["San Francisco", "New York"]` matches either city); different fields are AND'd together. Booleans such as `open_to_work` take a single value.

Filters that use a fixed vocabulary — `seniority`, `ownership`, `functions`, `degree_levels`, `fields_of_study`, `employment_types` — reject a value they don't recognise with a `422` that lists what is accepted. They never quietly return zero results for a word we couldn't read.

### Free text

**keyword** `string`

Keyword search across name and headline. Also accepted as `q`; if both are sent, `keyword` wins.

Words shorter than three characters are dropped, and the remaining words are OR'd — `"operations manufacturing quality"` matches a profile containing **any** of those words, not all three. Adding words broadens the search; use the structured filters below to narrow it.

Example: `software engineer`

### Location

**countries** `string[]`

Filter by country, matched exactly (case-insensitive) against the stored country name. For a substring match, include a `%` wildcard in the value — e.g. `["United %"]`.

Example: `["United States", "Canada"]`

**locations** `string[]`

Filter by full location string. Partial match. Example: `["Greater New York City Area"]`

**cities** `string[]`

Filter by city. Partial match, against both the parsed city and the full location string. Example: `["San Francisco", "Austin"]`

**states** `string[]`

Filter by state/region. Partial match, against both the parsed state and the full location string. Example: `["California"]`

### Current company

A "current" position is one the profile still holds — the company filters, `employment_types` and `employer_industries` all read it the same way.

**companies** `string[]`

Filter by current company name. Partial match. Example: `["Stripe", "Plaid"]`

**company\_linkedin\_urls** `string[]`

Filter by current company using its LinkedIn URL. Accepts a full URL, universal name, or numeric LinkedIn company ID.

Example: `["https://www.linkedin.com/company/stripe/"]`

**exclude\_company\_linkedin\_urls** `string[]`

Exclude profiles whose **current** company matches any of these LinkedIn URLs. Accepts the same formats as `company_linkedin_urls` (full URL, universal name, or numeric ID). Useful for filtering out a competitor or your own company from results.

Example: `["https://www.linkedin.com/company/competitor-co/"]`

**employer\_industries** `string[]`

Filter by the current employer's industry. Resolved from the employer's company page where the profile itself doesn't carry an industry, which answers for roughly three quarters of people.

Pass one of the [443 industry names](/api-reference/values/employer-industries). Case and punctuation are ignored, and **one name finds every spelling of the industry** — LinkedIn renamed 95 industries in 2022 and company pages still carry both vintages, so `Software Development` also matches the 2,246,742 occurrences filed as `computer software`. You don't need to pass both.

A shorthand of 4+ characters widens to the industries containing it: `Telecom` becomes telecommunications, telecommunications carriers, satellite telecommunications and media and telecommunications. A word we don't recognise is a `422` with near misses, never an empty result.

Example: `["Financial Services", "Software Development"]`

### Past company

**past\_companies** `string[]`

Filter by a company the person has **left** (the position has an end date). Partial match. Example: `["Google"]`

**past\_company\_linkedin\_urls** `string[]`

Same as `past_companies`, by LinkedIn URL, universal name, or numeric ID.

Example: `["https://www.linkedin.com/company/google/"]`

### Role

**job\_titles** `string[]`

Filter by job title. Partial match, against **any** position on the profile — current or past. Use `seniority` or `functions` when you want the role the person holds now.

Example: `["CTO", "VP of Engineering"]`

**seniority** `string[]`

Filter by the seniority of the current role, derived from the job title.

Accepts our own labels — `Intern`, `Entry`, `Individual`, `Senior`, `Lead`, `Manager`, `Director`, `VP`, `C-suite` — or the LinkedIn Sales Navigator words the [ICP People Search](/api-reference/endpoints/icp-people-search) endpoint uses (`cxo`, `c-level`, `vice president`, `vp`, `director`, `manager`, `experienced manager`, `entry level manager`, `strategic`, `senior`, `entry level`, `in training`, `intern`). Spelling is forgiving about case, spaces, hyphens and underscores.

`owner`, `founder` and `partner` are accepted here too and resolve to the ownership axis below, so `["VP", "founder"]` returns both groups.

Example: `["VP", "C-suite"]`

**ownership** `string[]`

Filter by ownership of the business, which is a separate axis from seniority — an owner is not a rung above a VP. Accepted values: `owner_founder` (also spelled `owner`, `founder`, `co-founder`, `self employed`) and `partner`.

Example: `["owner_founder"]`

**functions** `string[]`

Filter by department/function of the current role, from Datamagnet's 40-function taxonomy. Accepts the name or its numeric id.

`Software Engineering`, `Data & Analytics`, `IT & Systems`, `Information Security`, `Infrastructure & DevOps`, `Quality Assurance`, `Product Management`, `Design & UX`, `Sales`, `Business Development`, `Marketing`, `Revenue Operations`, `Customer Success`, `Customer Support`, `Finance`, `Accounting`, `Legal & Compliance`, `Human Resources`, `Recruiting & Talent`, `Administrative`, `Business Operations`, `Supply Chain & Logistics`, `Manufacturing & Production`, `Procurement`, `Engineering (non-software)`, `Construction & Skilled Trades`, `Facilities & Real Estate`, `Transportation & Drivers`, `Consulting`, `Healthcare & Clinical`, `Education & Teaching`, `Research & Science`, `Media & Communications`, `Arts & Entertainment`, `Hospitality & Food Service`, `Retail`, `Public Sector`, `Protective Services`, `Social & Community Services`, `Agriculture & Environment`.

Titles that name no department (a bare "Founder", for example) hold no function and are excluded rather than guessed at.

Example: `["Sales", "Marketing"]`

**employment\_types** `string[]`

Filter by the employment type of the **current** role. Accepted values: `full_time`, `part_time`, `contract`, `freelance`, `self_employed`, `internship`, `apprenticeship`, `seasonal`.

Each value covers the spellings LinkedIn uses for it — `contract` also matches `Temporary`, `internship` also matches `Co-op`, and so on. A profile whose employment type was never recorded matches none of them.

Example: `["contract", "freelance"]`

### Tenure

These read the start date of the current role. That date is as fresh as the profile's last refresh, so a very recent job change may not be reflected yet — the filter can miss a change, never invent one.

**changed\_jobs\_within\_days** `integer`

Started their current role within the last N days. Example: `90`

**min\_months\_in\_role** `integer`

At least N months in the current role. Example: `12`

**max\_months\_in\_role** `integer`

At most N months in the current role. Example: `6`

### Education

The education filters must all be satisfied by the **same** degree — `degree_levels: ["bachelor"]` with `fields_of_study: ["Computer and Information Sciences"]` means one bachelor's in computing, not a bachelor's in history plus a doctorate in computing.

**schools** `string[]`

Filter by school name. Partial match. Example: `["Stanford"]`

**degree\_levels** `string[]`

Accepted values: `secondary`, `associate`, `bachelor`, `master`, `doctorate`. Common spellings resolve to these — `bachelors`, `masters`, `phd`, `high school`.

Example: `["bachelor", "master"]`

**fields\_of\_study** `string[]`

Filter by field of study, grouped into 47 CIP families. Accepts the family name or its numeric id — e.g. `Computer and Information Sciences`, `Engineering`, `Business, Management, Marketing and Related Support Services`, `Health Professions and Related Programs`, `Social Sciences`. A `422` lists all of them.

Example: `["Computer and Information Sciences"]`

**graduation\_year\_min** `integer`

Degree ended in or after this year. Example: `2015`

**graduation\_year\_max** `integer`

Degree ended in or before this year. Example: `2020`

### Credentials and skills

**skills** `string[]`

Filter by listed skill, matched exactly (case-insensitive) against the skill name. Example: `["Kubernetes", "Terraform"]`

**certifications** `string[]`

Filter by certification name. Partial match. Must hold on the same certification as `certification_issuers`. Example: `["AWS Certified Solutions Architect"]`

**certification\_issuers** `string[]`

Filter by issuing organization. Partial match. Example: `["Amazon Web Services"]`

**languages** `string[]`

Filter by a language listed on the profile, matched exactly (case-insensitive) as LinkedIn spells it. Example: `["German", "Spanish"]`

### Profile attributes

**open\_to\_work** `boolean`

Filter by the LinkedIn open-to-work badge.

This filter is tri-state rather than a plain on/off switch. `true` returns profiles where the badge was seen. `false` returns profiles whose badge status was checked and did not show it. Profiles nobody has checked yet hold no badge information at all and are excluded from both sides, so `false` is **not** the complement of `true`, and leaving the field out is not the same as sending `false`.

Example: `true`

**is\_premium** `boolean`

Filter by LinkedIn Premium. Example: `true`

**is\_creator** `boolean`

Filter by LinkedIn creator mode. Example: `true`

**min\_followers** `integer`

Minimum follower count. Example: `1000`

### Contactability

**has\_email** `boolean`

`true` returns only profiles Datamagnet currently holds an email address for; `false` returns only those it holds none for. Like `open_to_work`, this describes our records, not the person — `false` is not a claim that they have no email.

Example: `true`

**has\_phone** `boolean`

As `has_email`, for phone numbers. Example: `true`

### Response shape and paging

**raw\_data** `boolean` (default: true)

Whether to include the full `raw_data` payload on each result. Send `false` to omit it — the response is much smaller and the search is faster, and every other field is unaffected.

**limit** `integer` (default: 50)

Maximum number of results to return per page, from `1` to `50`. A value outside that range is rejected rather than quietly reduced — page through larger result sets with `offset`.

**offset** `integer` (default: 0)

Number of results to skip, for pagination.

### Unrecognised fields

A field name this endpoint doesn't know is not applied. The search still runs, and the response carries an `ignored_filters` array naming what was dropped — so a mistyped `job_title` (for `job_titles`) shows up as a named mistake instead of a page of results that looks filtered but isn't.

If **every** filter in the request was unrecognised, the search is refused with a `422` and no credits are charged, rather than run as an unfiltered scan of the whole database.

***

## Response

```json Request theme={null}
{
  "keyword": "software engineer",
  "cities": ["San Francisco"],
  "company_linkedin_urls": ["https://www.linkedin.com/company/stripe/"],
  "exclude_company_linkedin_urls": ["https://www.linkedin.com/company/competitor-co/"],
  "job_titles": ["Backend Engineer"],
  "seniority": ["Senior", "Lead"],
  "functions": ["Software Engineering"],
  "degree_levels": ["bachelor"],
  "min_months_in_role": 12,
  "has_email": true,
  "open_to_work": true,
  "raw_data": false,
  "limit": 50,
  "offset": 0
}
```

```json Response theme={null}
{
  "message": [
    {
      "id": 10432,
      "entity_urn": "ACoAAC8Np1kB17Ro_b3eo8YZWUZFudbt9lrg1Tw",
      "username": "jane-doe-1234",
      "full_name": "Jane Doe",
      "display_name": "Jane Doe",
      "profile_headline": "Backend Engineer at Stripe",
      "description": "Building payments infrastructure.",
      "profile_link": "https://linkedin.com/in/jane-doe-1234",
      "location": "San Francisco, California, United States",
      "location_city": "San Francisco",
      "location_state": "California",
      "country": "United States",
      "followers": 1240,
      "connections": 500,
      "is_premium": true,
      "is_creator": false,
      "is_influencer": false,
      "is_job_seeker": false,
      "is_openlink": false,
      "is_retired": false,
      "open_to_work": true,
      "avatar_url": "https://media.licdn.com/dms/image/...",
      "profile_picture": "https://media.licdn.com/dms/image/...",
      "email": null,
      "linkedin_url": "https://linkedin.com/in/jane-doe-1234",
      "current_job_title": "Backend Engineer",
      "current_company": "Stripe",
      "current_job_location": "San Francisco, CA",
      "current_employment_type": "Full-time"
    }
  ],
  "credit_used": 10,
  "total": 1
}
```

## The response model

### Properties

**message** `array`

List of matching profiles.

**Profile object**

**id** `integer`

Internal Datamagnet profile ID.

**entity\_urn** `string`

LinkedIn entity URN.

**username** `string`

LinkedIn username/vanity URL.

**full\_name** `string`

Full name of the person.

**display\_name** `string`

Display name as shown on LinkedIn.

**profile\_headline** `string`

LinkedIn profile headline.

**description** `string`

Profile description/about section.

**profile\_link** `string`

LinkedIn profile URL.

**location** `string`

Full location string.

**location\_city** `string`

City of the profile's location.

**location\_state** `string`

State/region of the profile's location.

**country** `string`

Country of the profile's location.

**followers** `integer`

Number of LinkedIn followers.

**connections** `integer`

Number of LinkedIn connections.

**is\_premium** `boolean`

Whether the person has LinkedIn Premium.

**is\_creator** `boolean`

Whether the person is a LinkedIn creator.

**is\_influencer** `boolean`

Whether the person is a LinkedIn influencer.

**is\_job\_seeker** `boolean`

Whether the person is marked as a job seeker.

**is\_openlink** `boolean`

Whether the person uses OpenLink.

**is\_retired** `boolean`

Whether the person is marked as retired.

**open\_to\_work** `boolean`

Whether the person carries the LinkedIn open-to-work badge. `null` when the badge status has not been checked for this profile, which is true of most of the database — it is not the same as `false`.

**avatar\_url** `string`

Profile picture URL.

**profile\_picture** `string`

Alternate profile picture URL.

**email** `string`

Email address, when available. May be `null`.

**linkedin\_url** `string`

Computed LinkedIn profile URL, built from `username`.

**current\_job\_title** `string`

Job title of the profile's current position, when available.

**current\_company** `string`

Name of the profile's current company, when available.

**current\_job\_location** `string`

Location of the profile's current position, when available.

**current\_employment\_type** `string`

Employment type of the current position (e.g. `Full-time`), when available.

**raw\_data** `object`

The full stored payload this profile was built from. Included by default; send `raw_data: false` in the request to omit it.

**credit\_used** `integer`

Number of credits used for this request. Example: `10`

**total** `integer`

Number of results returned in this response.

**ignored\_filters** `string[]`

Present only when the request contained field names this endpoint doesn't recognise. Names them, so a typo shows up as a typo rather than as results that look filtered but aren't. The rest of the search ran normally.

## Errors

| Status | Meaning | What to do |
| - | - | - |
| `400` | The body was not a JSON object, or `limit` was outside `1`–`50`, or `offset` was negative. `message` names the problem. | Fix the request. |
| `422` | Either every filter in the request was an unrecognised field name, or a fixed-vocabulary filter was given a value that doesn't exist — an unknown function, a degree level that isn't one of the five, an industry that is none of the [443](/api-reference/values/employer-industries). `message` names what was rejected and lists what is accepted. | Correct the name or the value. |
| `504` | The search ran too long to answer. | Narrow it and retry — fewer countries, a more specific job title. A broad `keyword` with no structured filter beside it is the usual cause. |

Nothing is charged on any error.


# Post Comments
Source: https://docs.datamagnet.co/api-reference/endpoints/post-comments

POST https://api.datamagnet.co/api/v1/post/comments
Retrieve all comments on a LinkedIn post by URL, including commenter profiles, comment text, timestamps, and reply threads for engagement analysis.

# Post Comments

**Cost:** `10` credits / successful request.

This endpoint retrieves comments from a LinkedIn post. Simply provide the LinkedIn post URL and the API will extract the activity ID automatically and return paginated comments.

## Post comments endpoint

This endpoint allows you to get comments from any LinkedIn post by providing its URL.

### Required attributes

**url** `string` *required*

The LinkedIn post URL. Supports multiple URL formats:

* `https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX`
* `https://www.linkedin.com/posts/username_slug-ugcPost-7430527985071595520-XXXX`
* `https://www.linkedin.com/feed/update/urn:li:activity:7430615551086850048`

### Optional attributes

**page** `integer` (default: 1)

Page number for pagination. Use the `cursor` value from the previous response to get the next page. You can send it as `page` or as `cursor`; if you send both, `page` is used.

**sort** `string`

Order of the comments: `"recent"` (newest first) or `"relevance"`. When omitted, comments are returned newest first. Any other value returns a `400`.

### Response

```json Response theme={null}
{
  "cursor": null,
  "message": {
    "comments": [
      {
        "commenter": {
          "navigation_url": "https://www.linkedin.com/company/example-co/posts",
          "subtitle": "22,134 followers",
          "title": "Example Co"
        },
        "edited": false,
        "permalink": "https://www.linkedin.com/feed/update/urn:li:activity:7321383686006882304?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7321383686006882304%2C7321434896030183426%29&dashCommentUrn=urn%3Ali%3Afsd_comment%3A%287321434896030183426%2Curn%3Ali%3Aactivity%3A7321383686006882304%29",
        "pinned": false,
        "reaction_type_counts": [],
        "replies_count": 0,
        "text": "Awesome work Pratik Dani ❤️ ",
        "timestamp": 1745566104897,
        "top_replies": []
      },
      {
        "commenter": {
          "image": "https://media.licdn.com/dms/image/v2/D5603AQGBD4qUbB0j0A/profile-displayphoto-crop_800_800/B56ZhbUiPVHMAI-/0/1753878768080?e=1773273600&v=beta&t=92JTYvAs8ZBUhsC2K5eJ0P3NzfB8ND8EM-iTajxtvUk",
          "navigation_url": "https://www.linkedin.com/in/anushka-tripathi-33631a21a",
          "sales_nav_id": "ACoAADbZ2yIBx1dPq0aN7v8EXAMPLEidY4mVt0",
          "subtitle": "M.A. Public Policy",
          "title": "Anushka Tripathi"
        },
        "edited": false,
        "permalink": "https://www.linkedin.com/feed/update/urn:li:activity:7321383686006882304?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7321383686006882304%2C7321422705793118208%29&dashCommentUrn=urn%3Ali%3Afsd_comment%3A%287321422705793118208%2Curn%3Ali%3Aactivity%3A7321383686006882304%29",
        "pinned": false,
        "reaction_type_counts": [],
        "replies_count": 0,
        "text": "Many congratulations 🎉",
        "timestamp": 1745563198517,
        "times": "2025-04-25T06:39:58.517Z",
        "top_replies": []
      }
    ],
    "total": 2
  }
}
```

## The post comments model

### Properties

**cursor** `integer | null`

The next page number for pagination. Pass this value as the `page` parameter in your next request. Returns `null` when there are no more pages.

**message** `object`

The response payload containing comments.

**Message object**

**total** `integer`

Number of top-level comments on the post. Replies are not counted here: they are returned nested inside each comment (`top_replies`, counted by `replies_count`). The comment count LinkedIn shows on a post includes replies, so it is usually higher than `total`.

**comments** `array`

List of comment objects.

**Comment object**

**text** `string`

The comment text content.

**permalink** `string`

Direct permalink to the comment on LinkedIn.

**timestamp** `number`

Unix timestamp (milliseconds) when the comment was posted.

**times** `string`

The same moment as `timestamp`, as an ISO 8601 string (e.g. `"2026-02-22T16:46:14.489Z"`).

**pinned** `boolean`

Whether the comment is pinned by the post author.

**edited** `boolean`

Whether the comment has been edited.

**replies\_count** `integer`

Number of replies to this comment.

**mentions** `array`

People and companies tagged in the comment. Empty when nobody is tagged. Replies in `top_replies` carry the same array.

**Mention object**

**entity\_urn** `string`

URN of the tagged profile (`urn:li:fsd_profile:…`) or company (`urn:li:fsd_company:…`).

**name** `string`

Name of the tagged person or company.

**type** `string`

`"profileMention"` or `"companyMention"`.

#### Commenter

**commenter** `object`

Details about who wrote the comment. Usually a member, but company and school pages comment too: check `navigation_url` (`/in/`, `/company/`, `/school/`).

**Commenter object**

**title** `string`

Commenter's name.

**subtitle** `string`

Commenter's LinkedIn headline.

**image** `string`

Commenter's profile picture URL. `null` or absent when the commenter has no picture.

**navigation\_url** `string`

Link to the commenter's LinkedIn profile or page.

**sales\_nav\_id** `string`

The commenter's LinkedIn member id (`ACoA…`), the id in `urn:li:fsd_profile:<id>`. Absent for company and school pages.

#### Engagement

**reaction\_type\_counts** `array`

Breakdown of reactions on the comment.

**Reaction object**

**count** `number`

Number of this reaction type.

**type** `string`

Reaction type: `"LIKE"`, `"PRAISE"`, `"EMPATHY"`, `"ENTERTAINMENT"`, etc.

**top\_replies** `array`

Replies to the comment (if any), in the same shape as a comment.

## Pagination

To paginate through all comments:

1. Make an initial request without the `page` parameter (defaults to page 1).
2. Check the `cursor` field in the response.
3. If `cursor` is not `null`, make another request with `page` set to the `cursor` value.
4. Repeat until `cursor` returns `null`.

```python Example theme={null}
import requests

url = "https://api.datamagnet.co/api/v1/post/comments"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
page = 1
all_comments = []

while page is not None:
    response = requests.post(url, json={
        "url": "https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX",
        "page": page
    }, headers=headers)

    data = response.json()
    all_comments.extend(data["message"]["comments"])
    page = data.get("cursor")

print(f"Total comments fetched: {len(all_comments)}")
```


# Post Details
Source: https://docs.datamagnet.co/api-reference/endpoints/post-detail

POST https://api.datamagnet.co/api/v1/post
Retrieve detailed information about a single LinkedIn post by URL, including author, content, media, engagement counts, and publish timestamp.

# Post Details

**Cost:** `1` credit / successful request.

This endpoint retrieves comprehensive details about a single LinkedIn post, including the post text, author information, social engagement metrics, attachments, and repost information.

> [!NOTE]
>
> **This page is the current contract for `POST /api/v1/post`.** Engagement counts live
> under `social_count` (`num_likes`, `num_comments`, `num_shares`) and the publish time is
> `posted_at`. There is no `engagement` object and no `created_at` field.
>
> Do not confuse this with the deprecated `POST /api/v1/posts` (plural), a legacy
> alias that reads the public page and returns a different, less reliable shape.

## Post details endpoint

This endpoint allows you to get full details of any LinkedIn post by providing its URL.

### Required attributes

**url** `string` *required*

The LinkedIn post URL. Supports multiple URL formats:

* `https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX`
* `https://www.linkedin.com/posts/username_slug-ugcPost-7430527985071595520-XXXX`
* `https://www.linkedin.com/feed/update/urn:li:activity:7430615551086850048`

### Response

```json Response theme={null}
{
  "message": {
    "post_text": "We're growing the Product team! We're looking for a talented PM to help us drive subscription revenue. Check out the link below if you fit the bill.",
    "post_link": "https://www.linkedin.com/feed/update/urn:li:activity:7219434359085252608",
    "links_in_post": [],
    "image_component_all_dimentions": [],
    "actor": {
      "actor_image": "https://media.licdn.com/dms/image/...",
      "actor_description": "VP of Product at ExampleCo",
      "actor_name": "John Smith",
      "actor_sub_description": "1yr • Edited •   ",
      "actor_link": "https://www.linkedin.com/in/johnsmith..."
    },
    "header": {
      "actor_image": "https://media.licdn.com/dms/image/...",
      "actor_description": "Product Community Manager at ExampleCo",
      "actor_name": "Product Community",
      "actor_sub_description": "1yr • Edited •   ",
      "actor_link": "https://www.linkedin.com/company/product-community..."
    },
    "is_repost": true,
    "reshared_post": {
      "post_text": "We're growing the Product team! ...",
      "post_link": "https://www.linkedin.com/feed/update/urn:li:activity:7219379021761916928",
      "links_in_post": [],
      "actor": {
        "actor_image": "https://media.licdn.com/dms/image/...",
        "actor_description": "VP of Product at ExampleCo",
        "actor_name": "John Smith",
        "actor_sub_description": "1yr",
        "actor_link": "https://www.linkedin.com/in/johnsmith..."
      },
      "posted_at": "2024-07-17T18:02:11.000Z",
      "posted_ago": "1yr",
      "urn": "urn:li:activity:7219379021761916928"
    },
    "social_count": {
      "num_likes": 124,
      "num_comments": 11,
      "num_shares": 13,
      "reaction_type_counts": [
        {
          "count": 108,
          "reaction_type": "LIKE"
        },
        {
          "count": 10,
          "reaction_type": "PRAISE"
        },
        {
          "count": 4,
          "reaction_type": "EMPATHY"
        }
      ]
    },
    "posted_at": "2024-07-17T20:14:41.000Z",
    "posted_ago": "1yr • Edited •   ",
    "urn": "urn:li:activity:7219434359085252608",
    "reactions_urn": "urn:li:activity:7219379021761916928",
    "comments_urn": "urn:li:fsd_socialDetail:(urn:li:activity:7219379021761916928,urn:li:activity:7219434359085252608,urn:li:highlightedReply:-)",
    "reposts_urn": "urn:li:activity:7219379021761916928"
  },
  "credit_used": 1
}
```

## The post details model

### Properties

**message** `object`

The post details payload.

**Post object**

#### Post Content

**post\_text** `string`

The full text content of the post.

**post\_link** `string`

Direct LinkedIn URL to the post.

**posted\_at** `string`

ISO 8601 timestamp when the post was published, e.g. `"2024-07-17T20:14:41.000Z"`.
This is the field to sort and filter on.

**posted\_ago** `string`

Human-readable age of the post, exactly as LinkedIn renders it (e.g. `"1yr • Edited •"`).
This is a display string whose wording varies, so parse `posted_at` instead.

**urn** `string`

Unique LinkedIn URN identifier for the post.

**is\_repost** `boolean`

Whether this post is a repost of another post.

**links\_in\_post** `array`

List of URLs found in the post text.

#### Author

**actor** `object`

Details about the post author.

**Actor object**

**actor\_name** `string`

Author's name.

**actor\_description** `string`

Author's LinkedIn headline.

**actor\_sub\_description** `string`

Time since post and visibility info.

**actor\_image** `string`

URL to the author's profile picture.

**actor\_link** `string`

Link to the author's LinkedIn profile.

#### Media

**image\_component\_all\_dimentions** `array`

Media attached to the post, in every dimension LinkedIn serves. Item shape is
passed through as LinkedIn returns it and is not normalised, so treat entries
as opaque objects rather than depending on a fixed key set. Empty array when the
post has no media.

#### Reposts

**header** `object | null`

On a repost, the account that reshared it. `null` on an original post.

Note that LinkedIn's own feed structure puts the **original** author in `actor`
and the resharer in `header`, and this endpoint mirrors that. `header` uses the
same five `actor_*` keys as the actor object above.

**reshared\_post** `object | null`

The original post behind a repost. `null` on an original post.

**Reshared post object**

**post\_text** `string`

Text of the original post.

**post\_link** `string`

LinkedIn URL of the original post.

**links\_in\_post** `array`

URLs found in the original post text.

**actor** `object`

The original author, in the same actor shape described above.

**posted\_at** `string`

When the original post was published.

**posted\_ago** `string`

Human-readable age of the original post.

**urn** `string | null`

URN of the original post. May be `null`.

#### Social Engagement

**social\_count** `object`

Engagement metrics for the post.

**Social count object**

**num\_likes** `integer`

Total number of reactions.

**num\_comments** `integer`

Number of comments.

**num\_shares** `integer`

Number of shares/reposts.

**reaction\_type\_counts** `array`

Breakdown of reactions by type.

**Reaction type count**

**count** `integer`

Number of this reaction type.

**reaction\_type** `string`

Type of reaction: `"LIKE"`, `"PRAISE"`, `"EMPATHY"`, `"INTEREST"`, `"APPRECIATION"`, `"ENTERTAINMENT"`.

#### Related URNs

**reactions\_urn** `string`

URN to use for fetching reactions via the Post Reactions endpoint.

**comments\_urn** `string`

URN to use for fetching comments via the Post Comments endpoint.

**reposts\_urn** `string`

URN to use for fetching reposts via the Post Reposts endpoint.

**credit\_used** `integer`

Number of credits consumed by this request.


# Post Reactions
Source: https://docs.datamagnet.co/api-reference/endpoints/post-reactions

POST https://api.datamagnet.co/api/v1/post/reactions
Retrieve reactions on a LinkedIn post — likes, praise, empathy, insightful, and more — along with each reactor's profile for lead generation.

# Post Reactions

**Cost:** `10` credits / successful request.

This endpoint retrieves all reactions on a LinkedIn post. Simply provide the LinkedIn post URL and the API will return paginated reactions with user details and reaction types.

## Post reactions endpoint

A repost is its own post with its own URL, and its reactions belong to the original post. For a repost found in [Company Posts](/api-reference/endpoints/company-posts), pass `original_post_url`.

This endpoint allows you to get reactions from any LinkedIn post by providing its URL.

### Required attributes

**url** `string` *required*

The LinkedIn post URL. Supports multiple URL formats:

* `https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX`
* `https://www.linkedin.com/posts/username_slug-ugcPost-7430527985071595520-XXXX`
* `https://www.linkedin.com/feed/update/urn:li:activity:7430615551086850048`

### Optional attributes

**page** `integer` (default: 1)

Page number for pagination. Use the `cursor` value from the previous response to get the next page. You can send it as `page` or as `cursor`; if you send both, `page` is used.

### Response

```json Response theme={null}
{
  "cursor": 2,
  "message": {
    "reactions": [
      {
        "image": {
          "profile_pic": "https://media.licdn.com/dms/image/...",
          "profile_urn": "ACoAADRTEF0B..."
        },
        "subtitle": "Owner at Example Projects",
        "navigation_url": "https://www.linkedin.com/in/ACoAADRTEF0B...",
        "title": "Jane Smith",
        "action_urn": "urn:li:fsd_profile:ACoAADRTEF0B...",
        "actor": {
          "company_urn": null,
          "*profile_urn": "urn:li:fsd_profile:ACoAADRTEF0B..."
        },
        "reaction_type": "LIKE"
      },
      {
        "image": {
          "profile_pic": "https://media.licdn.com/dms/image/...",
          "profile_urn": "ACoAACx8oTYB..."
        },
        "subtitle": "Senior Engineer at TechCorp",
        "navigation_url": "https://www.linkedin.com/in/ACoAACx8oTYB...",
        "title": "Alex Johnson",
        "action_urn": "urn:li:fsd_profile:ACoAACx8oTYB...",
        "actor": {
          "company_urn": null,
          "*profile_urn": "urn:li:fsd_profile:ACoAACx8oTYB..."
        },
        "reaction_type": "PRAISE"
      },
      {
        "subtitle": "Product Manager | SaaS",
        "navigation_url": "https://www.linkedin.com/in/ACoAACeJDbcB...",
        "title": "Sofia Chen",
        "action_urn": "urn:li:fsd_profile:ACoAACeJDbcB...",
        "actor": {
          "company_urn": null,
          "*profile_urn": "urn:li:fsd_profile:ACoAACeJDbcB..."
        },
        "reaction_type": "LIKE"
      }
    ],
    "total": 211
  }
}
```

## The post reactions model

### Properties

**cursor** `integer | null`

The next page number for pagination. Pass this value as the `page` parameter in your next request. Returns `null` when there are no more pages.

**message** `object`

The response payload containing reactions.

**Message object**

**total** `integer`

Total number of reactions on the post.

**reactions** `array`

List of reaction objects.

**Reaction object**

**title** `string`

Name of the person, or the company page, that reacted.

**subtitle** `string`

LinkedIn headline of the person.

**navigation\_url** `string`

Link to the reactor's LinkedIn profile. For members this is usually the id form (`/in/ACoA…`), which opens the profile but is not the vanity URL; the [Person](/api-reference/endpoints/people) endpoint accepts it and returns the vanity username. A company page that reacted links to `/company/…`.

**reaction\_type** `string`

Type of reaction: `"LIKE"`, `"PRAISE"`, `"EMPATHY"`, `"INTEREST"`, `"APPRECIATION"`, `"ENTERTAINMENT"`. Every type is returned; filter on this field to keep only some.

**action\_urn** `string`

URN identifier for the person's profile. `null` for a company page.

**image** `object`

Profile image details (may be absent for some users).

**Image object**

**profile\_pic** `string`

URL to the profile picture. `null` when the reactor has none.

**profile\_urn** `string`

Profile URN identifier.

**actor** `object`

Actor details linking the reaction to a profile or company.

**Actor object**

**company\_urn** `string | null`

Not populated: always `null`. A company page that reacted is identified by its `navigation_url` (`/company/…`).

\***profile\_urn** `string`

Full profile URN identifier.

## Pagination

To paginate through all reactions:

1. Make an initial request without the `page` parameter (defaults to page 1).
2. Check the `cursor` field in the response.
3. If `cursor` is not `null`, make another request with `page` set to the `cursor` value.
4. Repeat until `cursor` returns `null`.

```python Example theme={null}
import requests

url = "https://api.datamagnet.co/api/v1/post/reactions"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
page = 1
all_reactions = []

while page is not None:
    response = requests.post(url, json={
        "url": "https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX",
        "page": page
    }, headers=headers)

    data = response.json()
    all_reactions.extend(data["message"]["reactions"])
    page = data.get("cursor")

print(f"Total reactions fetched: {len(all_reactions)}")
```


# Post Reposts
Source: https://docs.datamagnet.co/api-reference/endpoints/post-reposts

POST https://api.datamagnet.co/api/v1/post/reposts
Retrieve all reposts and shares of a LinkedIn post by URL, including the reposter's profile and any added commentary for amplification tracking.

# Post Reposts

**Cost:** `10` credits / successful request.

This endpoint retrieves all reposts of a LinkedIn post. Simply provide the LinkedIn post URL and the API will return paginated reposts with actor details and any commentary added.

## Post reposts endpoint

This endpoint allows you to get reposts from any LinkedIn post by providing its URL.

### Required attributes

**url** `string` *required*

The LinkedIn post URL. Supports multiple URL formats:

* `https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX`
* `https://www.linkedin.com/posts/username_slug-ugcPost-7430527985071595520-XXXX`
* `https://www.linkedin.com/feed/update/urn:li:activity:7430615551086850048`

### Optional attributes

**page** `integer` (default: 1)

Page number for pagination. Use the `cursor` value from the previous response to get the next page. You can send it as `page` or as `cursor`; if you send both, `page` is used.

### Response

```json Response theme={null}
{
  "cursor": 2,
  "message": {
    "reposts": [
      {
        "actor": {
          "name": "Sarah Williams",
          "image": {
            "profile_pic": "https://media.licdn.com/dms/image/...",
            "profile_urn": "ACoAABYJkyAB..."
          },
          "description": "Digital Consultant | SaaS Expert | AI Enthusiast",
          "sub_description": "1yr •   "
        },
        "commentary": "Great insights on professional development! Highly recommend reading this. #CareerGrowth"
      },
      {
        "header": {
          "reposter_image": {
            "profile_pic": "https://media.licdn.com/dms/image/...",
            "profile_urn": "ACoAACSnIRcB..."
          },
          "navigation_context": "https://www.linkedin.com/feed/update/urn:li:activity:...",
          "text": "Michael Chen reposted this",
          "image_navigation_context": "https://www.linkedin.com/in/michael-chen..."
        },
        "actor": {
          "name": "TechCo",
          "image": {
            "profile_pic": "https://media.licdn.com/dms/image/...",
            "company_id": "12345"
          },
          "description": "50,000 followers",
          "sub_description": "1yr •   "
        },
        "commentary": "What skills have contributed most to your career success?"
      },
      {
        "actor": {
          "name": "David Park",
          "image": {
            "profile_pic": "https://media.licdn.com/dms/image/...",
            "profile_urn": "ACoAAEAZv-UB..."
          },
          "description": "Senior Software Engineer at BigTech",
          "sub_description": "1yr •   "
        }
      }
    ],
    "total": 21
  }
}
```

## The post reposts model

### Properties

**cursor** `integer | null`

The next page number for pagination. Pass this value as the `page` parameter in your next request. Returns `null` when there are no more pages.

**message** `object`

The response payload containing reposts.

**Message object**

**total** `integer`

Total number of reposts of the post.

**reposts** `array`

List of repost objects.

**Repost object**

#### Actor (Original or Reposter)

**actor** `object`

Details about the person or company whose content appears in the repost.

**Actor object**

**name** `string`

Name of the person or company.

**description** `string`

LinkedIn headline or follower count (for companies).

**sub\_description** `string`

Time since repost and visibility info.

**image** `object`

Profile image details.

**Image object**

**profile\_pic** `string`

URL to the profile picture or company logo.

**profile\_urn** `string`

Profile URN (for individuals).

**company\_id** `string`

Company ID (for company pages).

**commentary** `string`

Text added by the reposter when sharing. May be absent if shared without commentary.

#### Repost Header (for reshares)

**header** `object`

Present when the repost is a reshare of someone else's content. Contains info about who reposted.

**Header object**

**text** `string`

Description of the repost action (e.g., "John Doe reposted this").

**navigation\_context** `string`

URL to the repost activity.

**reposter\_image** `object`

Image of the person who reposted.

**Reposter image**

**profile\_pic** `string`

URL to the reposter's profile picture.

**profile\_urn** `string`

Reposter's profile URN (for individuals).

**company\_id** `string`

Reposter's company ID (for company pages).

**image\_navigation\_context** `string`

URL to the reposter's profile.

## Pagination

To paginate through all reposts:

1. Make an initial request without the `page` parameter (defaults to page 1).
2. Check the `cursor` field in the response.
3. If `cursor` is not `null`, make another request with `page` set to the `cursor` value.
4. Repeat until `cursor` returns `null`.

```python Example theme={null}
import requests

url = "https://api.datamagnet.co/api/v1/post/reposts"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
page = 1
all_reposts = []

while page is not None:
    response = requests.post(url, json={
        "url": "https://www.linkedin.com/posts/username_slug-activity-7430615551086850048-XXXX",
        "page": page
    }, headers=headers)

    data = response.json()
    all_reposts.extend(data["message"]["reposts"])
    page = data.get("cursor")

print(f"Total reposts fetched: {len(all_reposts)}")
```


# Company Engagement Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-company-engagement

Monitor LinkedIn posts from specific target companies and surface qualified leads from the people who like, comment on, or share them in real time.

# Company Engagement Signal

The `company_engagement` signal monitors LinkedIn for posts originating from specific companies, extracts the people who liked or commented on those posts, filters them against your Ideal Customer Profile (ICP), and scores each lead 1–3 based on fit and intent.

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

***

## Create a company engagement signal

### Request

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

Must be `"company_engagement"`.

**company\_urls** `array` *required*

A list of LinkedIn company profile URLs to monitor. The system fetches each company page and extracts its numeric ID automatically. URLs that cannot be resolved are returned in `unresolved_company_urls` and skipped.

```json theme={null}
[
  "https://www.linkedin.com/company/salesforce/",
  "https://www.linkedin.com/company/hubspot/"
]
```

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

**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 posts 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](/api-reference/webhooks).

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json Response theme={null}
{
  "message": {
    "signal_id": "7c3e1f85-2a9d-4b6c-8e0f-d1a2b3c4d5e6",
    "signal_type": "company_engagement",
    "status": "active",
    "company_groups": [
      { "ids": [1441], "label": "Salesforce" },
      { "ids": [2382228], "label": "HubSpot" }
    ],
    "unresolved_company_urls": ["https://www.linkedin.com/company/nonexistent/"],
    "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 `"company_engagement"`.

**status** `string`

`"active"` after creation.

**company\_groups** `array`

The resolved company groups — one entry per successfully fetched URL, each with the company's LinkedIn `id` and `name` as the label.

**unresolved\_company\_urls** `array`

Only present if one or more `company_urls` could not be resolved. These companies are not being monitored. Verify the URL points to a valid LinkedIn company page.

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


# Create Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-create

POST https://api.datamagnet.co/api/v1/signal/create
Create a signal monitor that tracks LinkedIn profiles for job changes, new posts, or their own reactions and comments, or tracks keyword, industry, company, and person engagement events.

# Create Signal

Create a new signal monitor. The required fields depend on the `signal_type`.

| Signal type | Monitors |
| - | - |
| `job_change` | Job/company changes on tracked profiles |
| `new_post` | New LinkedIn posts from tracked profiles |
| `person_activity` | Reactions and comments the tracked people make, on anyone's post ([guide](/api-reference/endpoints/signal-person-activity)) |
| `keyword_engagement` | People engaging with posts matching your keywords |
| `industry_engagement` | People engaging with posts from target industries |
| `company_engagement` | People engaging with posts from specific companies |
| `person_engagement` | People engaging with posts from or about specific people |

***

## Schedule and name (all signal types)

These optional fields work with every `signal_type`.

**name** `string`

A display name for the signal, such as `"Champions"` or `"Competitor founders"`. It appears in `/signal/list` and in webhook payloads as `job_name`. Names don't need to be unique and never identify a signal; `signal_id` does. Defaults to the type's name, such as `"Job Change Monitor"`. Change it later with the [`rename` action](/api-reference/endpoints/signal-update).

**frequency** `string` (default: every\_day)

How often the signal runs: `"every_hour"`, `"every_2hr"`, `"every_12hr"`, `"every_day"`, or `"every_week"`.

**scheduled\_time** `string` (default: 09:00)

Time of day to run, `"HH:MM"` in UTC. For `every_hour` and `every_2hr`, only the minutes are used. For `every_12hr`, the signal runs at this time and 12 hours later, so `"09:00"` means 09:00 and 21:00 UTC. To spread load, a run can start after this time: up to about 20 minutes for hourly signals, 30 minutes for 12-hourly ones, an hour for daily ones, and 2 hours for weekly ones.

**scheduled\_day** `string` (default: monday)

Day of the week to run, for `every_week` only. For example `"monday"`.

***

## job\_change / new\_post / person\_activity

Track a list of LinkedIn profiles. `person_activity` has its own [guide](/api-reference/endpoints/signal-person-activity) with its webhook payload.

The first run for each profile records a baseline and reports nothing. After that, each run reports what changed since the last one.

### Required

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

`"job_change"`, `"new_post"`, or `"person_activity"`

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

A non-empty list of LinkedIn profile URLs to track.

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

### Optional

**signal\_id** `string`

Add `profile_urls` to this existing signal instead of creating one. The signal keeps its name, schedule, and other settings.

**new\_signal** `boolean` (default: false)

`true` always creates a new signal, even if you already have one of this type. Can't be combined with `signal_id`.

**activity\_types** `array`

`person_activity` only. What to report: `"reactions"`, `"comments"`, or both (the default).

**additional\_emails** `array`

Extra email addresses to notify when a signal fires. Your registered account email is always included automatically.

**webhook\_url** `string`

A URL to receive a POST request when a signal fires. See [Webhooks](/api-reference/webhooks) for the payload format.

**webhook\_secret** `string`

HMAC secret for signing webhook payloads. Adds an `X-Datamagnet-Signature` header to each delivery.

Plus `name`, `frequency`, `scheduled_time`, and `scheduled_day` from [Schedule and name](#schedule-and-name-all-signal-types).

### Several signals of one type

You can run several signals of the same type, for example a `job_change` signal for champions and another for churned customers. Each has its own profiles, baseline, and alerts, and a profile tracked by two signals alerts in both.

Which signal a create call affects:

| You send | You have | Result |
| - | - | - |
| `new_signal: true` | anything | A new signal |
| `signal_id` | that signal | The profiles are added to it |
| neither | no signal of this type | A new signal |
| neither | exactly one | The profiles are added to it |
| neither | several | `400`: pass `signal_id` or `new_signal: true` |

When profiles are added to an existing signal, only the schedule fields you send are applied; its name and other settings stay as they are.

**Credits:** `1` credit per profile in `profile_urls`.

### Response

```json job_change / new_post theme={null}
{
  "message": {
    "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
    "signal_type": "job_change",
    "name": "Champions",
    "status": "active",
    "profile_urls": [
      "https://linkedin.com/in/satyanadella",
      "https://linkedin.com/in/williamgates"
    ],
    "email_recipients": [
      "user@example.com",
      "teammate@example.com"
    ],
    "webhook_url": "https://yourapp.com/webhooks/signals"
  },
  "credit_used": 2
}
```

**message** `object`

**Fields**

**signal\_id** `string`

Unique identifier for this signal. **Save this**: use it to update, add profiles to, or delete this signal.

**signal\_type** `string`

The signal type.

**name** `string`

The signal's display name.

**status** `string`

`active` or `paused`.

**profile\_urls** `array`

All URLs the signal now tracks, including any it tracked before.

**activity\_types** `array`

`person_activity` only. What the signal reports.

**email\_recipients** `array`

Email addresses that will receive notifications.

**webhook\_url** `string`

Only present if configured.

> [!NOTE]
>
> Adding profiles to a paused signal is refused. Resume it first via [/signal/update](/api-reference/endpoints/signal-update) with `action: resume`.

***

## keyword\_engagement

Monitor LinkedIn for posts matching your keywords and surface the people who liked or commented on them, filtered and scored against your Ideal Customer Profile (ICP).

You can create **multiple** `keyword_engagement` signals, each targeting a different keyword set or ICP. Each signal is identified by a `signal_id` returned in the response.

For the full ICP field reference and lead scoring details, see the [Keyword Engagement guide](/api-reference/endpoints/signal-keyword-engagement).

### Required

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

`"keyword_engagement"`

**keywords** `array` *required*

Seed keywords to monitor. Minimum 1. The system automatically expands these with semantically related variants on the first run.

```json theme={null}
["sales intelligence", "CRM automation", "outbound prospecting"]
```

### Optional

**icp** `object`

Ideal Customer Profile filter. If omitted, every engaging lead is returned unfiltered. See the [ICP Filter Reference](/api-reference/endpoints/signal-keyword-engagement#icp-filter-reference) for all available fields.

```json theme={null}
{
  "job_titles": ["VP Sales", "Head of Revenue"],
  "seniority_levels": ["vp", "c_level", "director"],
  "industries": ["SaaS", "B2B Software"],
  "locations": ["United States", "United Kingdom"],
  "company_size": ["51 - 200", "201 - 500"],
  "exclude_titles": ["Intern", "Student"],
  "mandatory_keywords": ["sales"],
  "negative_keywords": ["recruiting", "hiring"]
}
```

**additional\_emails** `array`

Extra email addresses to receive the lead digest.

**webhook\_url** `string`

URL to receive qualified leads via POST after each run.

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json keyword_engagement theme={null}
{
  "message": {
    "signal_id": "9f4a2c81-3b7e-4d12-a5f1-c8e0d9b2f3a4",
    "signal_type": "keyword_engagement",
    "name": "CRM buyers",
    "status": "active",
    "keywords": ["sales intelligence", "CRM automation"],
    "icp": {
      "job_titles": ["VP Sales", "Head of Revenue"],
      "seniority_levels": ["vp", "c_level", "director"],
      "industries": ["SaaS", "B2B Software"]
    },
    "email_recipients": ["user@example.com"],
    "webhook_url": "https://yourapp.com/webhooks/signals"
  }
}
```

**message** `object`

**Fields**

**signal\_id** `string`

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

**signal\_type** `string`

Always `"keyword_engagement"`.

**status** `string`

Always `active` after creation.

**keywords** `array`

The seed keywords provided.

**icp** `object`

The ICP configuration, if provided.

**email\_recipients** `array`

Email addresses that will receive lead digests.

**webhook\_url** `string`

Only present if configured.

***

## industry\_engagement

Monitor LinkedIn for posts originating from companies in your target industries and surface the people who engage with them, filtered and scored against your Ideal Customer Profile.

You can create **multiple** `industry_engagement` signals — each identified by a `signal_id` returned in the response. See the [Industry Engagement guide](/api-reference/endpoints/signal-industry-engagement) for the full ICP reference and lead scoring details.

### Required

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

`"industry_engagement"`

**industries** `array` *required*

A list of LinkedIn industry names to monitor. Each name is resolved to its LinkedIn numeric ID automatically.

```json theme={null}
["software development", "financial services", "information technology and internet"]
```

Unrecognised names are returned in `unresolved_industries` and skipped.

### Optional

**icp** `object`

Ideal Customer Profile filter. See the [ICP Filter Reference](/api-reference/endpoints/signal-industry-engagement#icp-filter-reference) for all available fields.

**date\_posted** `string`

Only surface leads who engaged with posts published within this window. Valid values: `"past-24h"` · `"past-week"` · `"past-month"`

**additional\_emails** `array`

Extra email addresses to receive the lead digest.

**webhook\_url** `string`

URL to receive qualified leads via POST after each run.

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json industry_engagement theme={null}
{
  "message": {
    "signal_id": "3a1b9c42-7d2e-4f88-b6c1-e9f0a2d3c5b7",
    "signal_type": "industry_engagement",
    "name": "Fintech audience",
    "status": "active",
    "industry_groups": [
      { "ids": [4], "label": "software development" },
      { "ids": [43], "label": "financial services" }
    ],
    "unresolved_industries": ["saas tools"],
    "icp": {
      "seniority_levels": ["vp", "c_level", "director"]
    },
    "email_recipients": ["user@example.com"]
  }
}
```

**message** `object`

**Fields**

**signal\_id** `string`

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

**signal\_type** `string`

Always `"industry_engagement"`.

**status** `string`

Always `active` after creation.

**industry\_groups** `array`

The industry groups provided.

**icp** `object`

The ICP configuration, if provided.

**email\_recipients** `array`

Email addresses that will receive lead digests.

**webhook\_url** `string`

Only present if configured.

***

## company\_engagement

Monitor LinkedIn for posts from specific companies and surface the people who engage with them, filtered and scored against your Ideal Customer Profile.

You can create **multiple** `company_engagement` signals — each identified by a `signal_id` returned in the response. See the [Company Engagement guide](/api-reference/endpoints/signal-company-engagement) for the full ICP reference and lead scoring details.

### Required

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

`"company_engagement"`

**company\_urls** `array` *required*

A list of LinkedIn company profile URLs to monitor. The company ID is resolved automatically from each URL.

```json theme={null}
[
  "https://www.linkedin.com/company/salesforce/",
  "https://www.linkedin.com/company/hubspot/"
]
```

Unresolvable URLs are returned in `unresolved_company_urls` and skipped.

### Optional

**icp** `object`

Ideal Customer Profile filter. See the [ICP Filter Reference](/api-reference/endpoints/signal-company-engagement#icp-filter-reference) for all available fields.

**date\_posted** `string`

Only surface leads who engaged with posts published within this window. Valid values: `"past-24h"` · `"past-week"` · `"past-month"`

**additional\_emails** `array`

Extra email addresses to receive the lead digest.

**webhook\_url** `string`

URL to receive qualified leads via POST after each run.

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json company_engagement theme={null}
{
  "message": {
    "signal_id": "7c3e1f85-2a9d-4b6c-8e0f-d1a2b3c4d5e6",
    "signal_type": "company_engagement",
    "name": "Competitor audience",
    "status": "active",
    "company_groups": [
      { "ids": [1441], "label": "Salesforce" },
      { "ids": [2382228], "label": "HubSpot" }
    ],
    "unresolved_company_urls": ["https://www.linkedin.com/company/nonexistent/"],
    "icp": {
      "seniority_levels": ["vp", "c_level", "director"]
    },
    "email_recipients": ["user@example.com"]
  }
}
```

**message** `object`

**Fields**

**signal\_id** `string`

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

**signal\_type** `string`

Always `"company_engagement"`.

**status** `string`

Always `active` after creation.

**company\_groups** `array`

The company groups provided.

**icp** `object`

The ICP configuration, if provided.

**email\_recipients** `array`

Email addresses that will receive lead digests.

**webhook\_url** `string`

Only present if configured.

***

## person\_engagement

Monitor LinkedIn for posts and/or mentions from specific people and surface the users who engage with that content, filtered and scored against your Ideal Customer Profile.

You can create **multiple** `person_engagement` signals — each identified by a `signal_id` returned in the response. See the [Person Engagement guide](/api-reference/endpoints/signal-person-engagement) for the full ICP reference, tracking modes, and lead scoring details.

### Required

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

`"person_engagement"`

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

A list of LinkedIn profile URLs for the people to monitor. The `member_id` is resolved automatically from each profile.

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

Unresolvable URLs are returned in `unresolved_profile_urls` and skipped.

### Optional

**tracking\_mode** `string`

What content to monitor. `"posts"` — posts by the person · `"mentions"` — posts mentioning them · `"both"` (default) — both.

**icp** `object`

Ideal Customer Profile filter. See the [ICP Filter Reference](/api-reference/endpoints/signal-person-engagement#icp-filter-reference) for all available fields.

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

**webhook\_url** `string`

URL to receive qualified leads via POST after each run.

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json person_engagement theme={null}
{
  "message": {
    "signal_id": "b2d4f6a8-1c3e-5g7h-9i0j-k1l2m3n4o5p6",
    "signal_type": "person_engagement",
    "name": "Founder audiences",
    "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": {
      "seniority_levels": ["vp", "c_level", "director"]
    },
    "email_recipients": ["user@example.com"]
  }
}
```

**message** `object`

**Fields**

**signal\_id** `string`

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

**signal\_type** `string`

Always `"person_engagement"`.

**status** `string`

Always `active` after creation.

**person\_groups** `array`

The people being monitored.

**tracking\_mode** `string`

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

**icp** `object`

The ICP configuration, if provided.

**email\_recipients** `array`

Email addresses that will receive lead digests.

**webhook\_url** `string`

Only present if configured.


# Delete Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-delete

POST https://api.datamagnet.co/api/v1/signal/delete
Permanently delete a Datamagnet signal monitor by ID and remove all of its tracked profiles, events, and historical data from your account.

# Delete Signal

Permanently delete a signal monitor. This removes the job and all associated data from the database and cannot be undone.

> [!WARNING]
>
> This action is **irreversible**. All configuration and tracked data for the signal will be permanently removed.
> If you want to stop monitoring temporarily and resume later, use [/signal/update](/api-reference/endpoints/signal-update) with `action: "pause"` instead.

***

## Request

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

The type of signal to delete. Accepted values:

* `job_change`
* `new_post`
* `person_activity`
* `keyword_engagement`
* `industry_engagement`
* `company_engagement`
* `person_engagement`

**signal\_id** `string`

The ID of the signal to delete, from [/signal/create](/api-reference/endpoints/signal-create) or [/signal/list](/api-reference/endpoints/signal-list).

* **Any type, `signal_id` given:** deletes that one signal.
* **Engagement types, omitted:** deletes **all** signals of that `signal_type` for your account.
* **`job_change` / `new_post` / `person_activity`, omitted:** deletes your only signal of that type. If you have several, the request returns `400` and nothing is deleted; pass `signal_id`.

***

## Response

```json Single signal theme={null}
{
  "message": "Signal deleted successfully",
  "credit_used": 0
}
```

```json All signals of a type (no signal_id provided) theme={null}
{
  "message": "Deleted 3 signal(s) of type 'keyword_engagement'",
  "credit_used": 0
}
```

**message** `string`

Confirmation that the signal was permanently deleted.

**credit\_used** `integer`

Always `0`.

***

## Notes

* Returns `404` if the signal does not exist or does not belong to your account.
* For engagement types, omitting `signal_id` deletes every signal of that type for your account in one call. For profile types it deletes only when you have exactly one.
* To pause instead of delete, use [/signal/update](/api-reference/endpoints/signal-update) with `action: "pause"`.


# Industry Engagement Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-industry-engagement

Monitor LinkedIn posts from companies in target industries and surface qualified leads from the people who like, comment on, or share them.

# Industry Engagement Signal

The `industry_engagement` signal monitors LinkedIn for posts originating from companies in your target industries, extracts the people who liked or commented on those posts, filters them against your Ideal Customer Profile (ICP), and scores each lead 1–3 based on fit and intent.

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

***

## Create an industry engagement signal

### Request

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

Must be `"industry_engagement"`.

**industries** `array` *required*

A list of LinkedIn industry names to monitor. Each name is looked up in the LinkedIn industry taxonomy and resolved to its numeric ID automatically. Unrecognised names are returned in `unresolved_industries` and skipped.

```json theme={null}
["software development", "financial services", "information technology and internet"]
```

> [!NOTE]
>
> Names are matched case-insensitively. Use exact names from the LinkedIn industry list. Unrecognised names are reported in the response but do not cause the request to fail — as long as at least one name resolves.

**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 posts 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](/api-reference/webhooks).

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json Response theme={null}
{
  "message": {
    "signal_id": "3a1b9c42-7d2e-4f88-b6c1-e9f0a2d3c5b7",
    "signal_type": "industry_engagement",
    "status": "active",
    "industry_groups": [
      { "ids": [4], "label": "software development" },
      { "ids": [43], "label": "financial services" }
    ],
    "unresolved_industries": ["saas tools"],
    "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 `"industry_engagement"`.

**status** `string`

`"active"` after creation.

**industry\_groups** `array`

The resolved industry groups — one entry per successfully matched industry name, each with its LinkedIn `id` and the original `label`.

**unresolved\_industries** `array`

Only present if one or more `industries` names could not be matched. These entries were skipped and are not being monitored. Fix the spelling or use an exact name from the LinkedIn industry taxonomy.

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


# Keyword Engagement Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-keyword-engagement

Monitor LinkedIn for posts matching your keywords and surface qualified leads from the people who like, comment on, or share them as buying signals.

# Keyword Engagement Signal

The `keyword_engagement` signal monitors LinkedIn for posts matching your keywords, extracts the people who liked or commented on those posts, filters them against your Ideal Customer Profile (ICP), and scores each lead 1–3 based on fit and intent.

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

***

## Create a keyword engagement signal

### Request

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

Must be `"keyword_engagement"`.

**keywords** `array` *required*

Seed keywords to monitor on LinkedIn. Minimum 1. The system automatically expands these with semantically related variants on the first run.

```json theme={null}
["sales intelligence", "CRM automation", "outbound prospecting"]
```

**icp** `object`

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

**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](/api-reference/webhooks).

**webhook\_secret** `string`

HMAC secret for signing webhook payloads.

### Response

```json Response theme={null}
{
  "message": {
    "signal_id": "9f4a2c81-3b7e-4d12-a5f1-c8e0d9b2f3a4",
    "signal_type": "keyword_engagement",
    "status": "active",
    "keywords": ["sales intelligence", "CRM automation"],
    "icp": {
      "job_titles": ["VP Sales", "Head of Revenue"],
      "seniority_levels": ["vp", "c_level", "director"],
      "industries": ["SaaS", "B2B Software"],
      "locations": ["United States", "United Kingdom"],
      "company_size": ["51 - 200", "201 - 500"]
    },
    "email_recipients": ["user@example.com"],
    "webhook_url": "https://yourapp.com/webhooks/signals"
  }
}
```

**signal\_id** `string`

Unique identifier for this keyword engagement signal. **Save this** — you need it for update and delete operations.

**signal\_type** `string`

Always `"keyword_engagement"`.

**status** `string`

`"active"` after creation.

**keywords** `array`

The seed keywords you provided.

**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 — `"Computer Software"` matches `["SaaS", "Tech"]`. 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
* Keyword specificity: longer, more specific keywords score higher

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


# List Signal Leads
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-leads

POST https://api.datamagnet.co/api/v1/signal/leads
Fetch the leads your Datamagnet engagement signals have found. Filter by signal, lead score, keyword, engagement type, name or headline, and date, and page through your full history.

# List Signal Leads

Returns the leads your engagement signals ([`keyword_engagement`](/api-reference/endpoints/signal-keyword-engagement), [`industry_engagement`](/api-reference/endpoints/signal-industry-engagement), [`company_engagement`](/api-reference/endpoints/signal-company-engagement), and [`person_engagement`](/api-reference/endpoints/signal-person-engagement)) have stored, newest first. Use it to read past leads: to backfill after a missed [webhook](/api-reference/webhooks), to rebuild a report, or to pull only what is new since your last call.

The leads are always your own. They are found from your API key, so a request cannot name another account. This request costs no credits.

***

## Request

Every attribute is optional. With none, you get your 50 most recent leads across all your signals. Filters combine: a lead has to match all of the ones you send.

### Filters

**signal\_id** `string`

Only leads found by this signal. Get the ID from [/signal/create](/api-reference/endpoints/signal-create) or [/signal/list](/api-reference/endpoints/signal-list). A signal ID that is not yours returns an empty page.

**min\_score** `integer`

Only leads with a [lead score](/api-reference/endpoints/signal-keyword-engagement#lead-scoring) of at least this, from `1` to `3`.

**max\_score** `integer`

Only leads with a lead score of at most this, from `1` to `3`. Must not be lower than `min_score`.

**keyword** `string`

Only leads that this keyword, industry, company, or person label surfaced (the lead's `signal_keyword`). Matches the whole value, in any letter case. Up to 200 characters.

**engagement\_type** `string`

How the person engaged: `comment`, `like`, or another reaction such as `celebrate` or `support`. Any letter case. Up to 50 characters.

**search** `string`

Only leads whose name or headline contains this text, in any letter case. `%` and `_` are matched as themselves. Up to 100 characters.

**created\_from** `string`

Only leads found at or after this moment, as an ISO 8601 date or time, for example `2026-09-01` or `2026-09-01T09:00:00Z`. A date alone means the start of that day, and a time without a zone is read as UTC.

**created\_to** `string`

Only leads found before this moment, in the same format. Leads found exactly at this moment are not included. Must be later than `created_from`.

### Sorting and paging

**sort** `string` (default: created\_at\_desc)

The order of the leads:

* `created_at_desc`: newest first (default)
* `created_at_asc`: oldest first
* `lead_score_desc`: highest lead score first, newest first among equal scores
* `icp_score_desc`: best ICP fit first, newest first among equal scores

**limit** `integer` (default: 50)

Leads per page, from `1` to `200`.

**offset** `integer` (default: 0)

Leads to skip, from `0` to `1000000`. To go deeper than that, narrow the range with `created_from` and `created_to`.

Text values are trimmed of surrounding spaces. Any other attribute, including one that names a user or an email, is rejected with `400`, so a misspelled filter cannot quietly return unfiltered leads.

```json Request theme={null}
{
  "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
  "min_score": 2,
  "engagement_type": "comment",
  "created_from": "2026-09-01",
  "sort": "lead_score_desc",
  "limit": 50
}
```

***

## Response

```json Response theme={null}
{
  "message": {
    "total": 137,
    "limit": 50,
    "offset": 0,
    "has_more": true,
    "leads": [
      {
        "id": "0b9c6d5e-3f2a-4b1c-8d7e-6a5f4e3d2c1b",
        "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
        "linkedin_url": "https://linkedin.com/in/johndoe",
        "profile_name": "John Doe",
        "headline": "VP Sales at Acme Corp",
        "signal_keyword": "sales intelligence",
        "engagement_type": "comment",
        "engagement_post_url": "https://linkedin.com/posts/...",
        "comment_text": "Great point on outbound",
        "post_excerpt": "We just shipped a new way to prioritise outbound...",
        "post_author": "Jane Roe",
        "lead_score": 3,
        "icp_score": 0.87,
        "signal_score": 0.91,
        "icp_match_details": {
          "title": { "matched_target": "VP Sales", "seniority": "vp", "confidence": 0.95 },
          "industry": { "status": "match", "matched_target": "SaaS" },
          "company_size": "match",
          "location": "match"
        },
        "detected_at": "2026-09-24T09:15:00+00:00"
      }
    ]
  },
  "credit_used": 0
}
```

```json No leads theme={null}
{
  "message": {
    "total": 0,
    "limit": 50,
    "offset": 0,
    "has_more": false,
    "leads": []
  },
  "credit_used": 0
}
```

## Response fields

**message** `object`

**Page**

**total** `integer`

How many leads match your filters in all, not just on this page.

**limit** `integer`

The page size used.

**offset** `integer`

The number of leads skipped.

**has\_more** `boolean`

`true` when there are more leads after this page. Send `offset` plus `limit` to get them.

**leads** `array`

The leads on this page.

**Lead**

**id** `string`

The lead's unique ID. Stable, so you can use it to skip leads you already have.

**signal\_id** `string`

The signal that found the lead.

**linkedin\_url** `string`

The LinkedIn profile URL of the person who engaged.

**profile\_name** `string`

Full name of the person.

**headline** `string`

Their LinkedIn headline when the lead was found.

**signal\_keyword** `string`

The keyword, industry, company, or person label that surfaced the lead.

**engagement\_type** `string`

`comment`, or a reaction such as `like`, `celebrate`, or `support`.

**engagement\_post\_url** `string`

The LinkedIn post the person engaged with.

**comment\_text** `string | null`

The comment they left. `null` for reactions.

**post\_excerpt** `string | null`

The start of the post they engaged with. `null` if the post text could not be retrieved.

**post\_author** `string | null`

Who wrote the post. `null` if it could not be retrieved.

**lead\_score** `integer`

Overall lead quality, from `1` to `3`. See [lead scoring](/api-reference/endpoints/signal-keyword-engagement#lead-scoring).

**icp\_score** `number`

How well the lead fits your ICP, from `0.0` to `1.0`.

**signal\_score** `number`

Intent signal strength, from `0.0` to `1.0`.

**icp\_match\_details** `object`

How the lead matched the ICP filters on the signal. Which keys appear depends on the filters you set, for example `title`, `industry`, `company_size`, `location`, and `seniority`. Empty when the signal has no ICP.

**detected\_at** `string`

When the lead was **first** found, as an ISO 8601 time in UTC.

**credit\_used** `integer`

Always `0`.

***

## Getting all your leads

**Your whole history.** Page with `limit` and `offset` until `has_more` is `false`. Set `created_to` to the current time before your first request and keep it the same for the whole walk. Otherwise leads that arrive while you are paging shift the pages.

**Only what is new.** Send `sort` as `created_at_asc` and `created_from` set a minute before the newest `detected_at` you already have, then skip any `id` you already hold. Leads from one run are stored together and share a `detected_at`, and the minute of overlap covers a run that finishes just after another.

> [!NOTE]
>
> `detected_at` is when a lead was first found. If a later run finds the same person for the same keyword, it updates that lead's scores and post in place and keeps its `detected_at`, so a lead you already have can change without showing up again in a `created_from` request.

## Notes

* The lead fields are the same as in a [webhook](/api-reference/webhooks#engagement-signal-payload-fields), plus `id`, `signal_id`, and `icp_match_details`. `engagement_link` is not included, because the link to the exact comment is not stored: use `engagement_post_url`.
* Leads outlive their signal. Deleting a signal does not delete the leads it found, and they stay listed under its old `signal_id`.
* Returns `400` for an invalid filter, with a message that names the attribute, for example `min_score must be an integer from 1 to 3`.
* Returns `401` for an invalid API key, or when the account has no credits left, even though this request costs none.
* Returns `403` if your account does not have access to Signals. Contact [signals@datamagnet.co](mailto:signals@datamagnet.co).
* Returns `500` with `Failed to fetch leads` if the request could not be completed. Try again.


# List Signals
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-list

POST https://api.datamagnet.co/api/v1/signal/list
List the Datamagnet signal monitors on your account with their signal_id, name, type, status, and the LinkedIn profiles or targets they track.

# List Signals

Returns all signal monitors for your account, active and paused, each with the `signal_id` you use to update or delete it. Optionally filter by `signal_type`.

To read the leads your engagement signals have found, use [/signal/leads](/api-reference/endpoints/signal-leads).

## Request

### Optional attributes

**signal\_type** `string`

Return only signals of this type: `job_change`, `new_post`, `person_activity`, `keyword_engagement`, `industry_engagement`, `company_engagement`, or `person_engagement`.

Omit this field to return all your signals.

### Response

```json Response theme={null}
{
  "message": [
    {
      "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
      "signal_type": "job_change",
      "name": "Champions",
      "status": "active",
      "profile_urls": [
        "https://linkedin.com/in/satyanadella",
        "https://linkedin.com/in/williamgates"
      ],
      "email_recipients": ["user@example.com", "teammate@example.com"],
      "webhook_url": "https://yourapp.com/webhooks/signals"
    },
    {
      "signal_id": "3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
      "signal_type": "job_change",
      "name": "Churned customers",
      "status": "active",
      "profile_urls": ["https://linkedin.com/in/reidhoffman"],
      "email_recipients": ["user@example.com"]
    },
    {
      "signal_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "signal_type": "person_activity",
      "name": "Person Activity Monitor",
      "status": "paused",
      "profile_urls": ["https://linkedin.com/in/satyanadella"],
      "activity_types": ["reactions", "comments"],
      "email_recipients": ["user@example.com"]
    }
  ],
  "credit_used": 0
}
```

## Response fields

**message** `array`

Your signals, newest first. Engagement signals have their own fields (such as `keywords`, `icp`, or `person_groups`), as in their [create responses](/api-reference/endpoints/signal-create).

**Profile signal (job\_change / new\_post / person\_activity)**

**signal\_id** `string`

The signal's unique ID. Use it to update or delete this signal.

**signal\_type** `string`

`job_change`, `new_post`, or `person_activity`.

**name** `string`

The signal's display name.

**status** `string`

`active` or `paused`.

**profile\_urls** `array`

LinkedIn profile URLs currently being tracked.

**activity\_types** `array`

`person_activity` only. What the signal reports.

**email\_recipients** `array`

Email addresses that receive notifications when this signal fires.

**webhook\_url** `string`

Webhook URL for signal delivery. Only present if configured.


# Person Activity Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-person-activity

Get notified when the LinkedIn people you track react to or comment on any post, with the post, its author, and their comment text.

# Person Activity Signal

The `person_activity` signal tells you when a person you track **reacts to or comments on anything** on LinkedIn: their likes and other reactions, their comments, and their replies to comments, on anyone's post.

Use it to see what a champion, prospect, or competitor's executive is paying attention to, and to reach out while it is fresh.

> [!NOTE]
>
> `person_activity` is the opposite direction from [`person_engagement`](/api-reference/endpoints/signal-person-engagement):
>
> * **person\_activity**: what the tracked person does. *"Satya liked a post by Ryan Roslansky."*
> * **person\_engagement**: who engages with the tracked person's content. *"Taylor commented on Satya's post."*

You can run **several** `person_activity` signals, for example one for champions and one for churned customers. Each is identified by its `signal_id` and can carry a `name` for display. A person tracked by two signals triggers alerts from both.

***

## How it works

1. **First run: baseline.** For each profile, the signal records the person's current activity and reports nothing. You receive one `baseline` webhook listing the profiles now being tracked.
2. **Every run after that:** each reaction, comment, and reply the person made since the last run is reported **once**, oldest first.
3. **Runs follow the signal's schedule** (`frequency`, default once a day). See [Create Signal](/api-reference/endpoints/signal-create#schedule-and-name-all-signal-types).

`occurred_at` on each item is when the person reacted or commented, not when the post was published.

***

## Create a person activity signal

`POST https://api.datamagnet.co/api/v1/signal/create`

### Request

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

Must be `"person_activity"`.

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

LinkedIn profile URLs of the people to track.

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

**activity\_types** `array` (default: \["reactions", "comments"])

What to report. `"reactions"`, `"comments"`, or both. Replies to comments count as comments.

Each type is a separate check per profile per run, so tracking only one halves the cost of each run.

**name** `string`

A display name for this signal, such as `"Champions"`. Optional; defaults to `"Person Activity Monitor"`. Change it later with the `rename` action.

**new\_signal** `boolean` (default: false)

Set to `true` to create another `person_activity` signal when you already have one. Without it, profiles are added to your existing signal. See [Several signals of one type](/api-reference/endpoints/signal-create#several-signals-of-one-type).

**signal\_id** `string`

Add these profiles to an existing `person_activity` signal instead of creating one.

**frequency** `string` (default: every\_day)

How often the signal runs: `"every_hour"`, `"every_2hr"`, `"every_12hr"`, `"every_day"`, or `"every_week"`.

**additional\_emails** `array`

Extra email addresses to notify. Your account email is always included.

**webhook\_url** `string`

URL to receive activity via `POST`. See [Webhook payload](#webhook-payload) below.

**webhook\_secret** `string`

HMAC secret for signing webhook payloads. See [Verifying webhook signatures](/api-reference/webhooks#verifying-webhook-signatures).

```json Request theme={null}
{
  "signal_type": "person_activity",
  "name": "Champions",
  "profile_urls": ["https://www.linkedin.com/in/satyanadella"],
  "activity_types": ["reactions", "comments"],
  "frequency": "every_day",
  "webhook_url": "https://yourapp.com/webhooks/signals",
  "webhook_secret": "your-hmac-secret"
}
```

### Response

```json Response theme={null}
{
  "message": {
    "signal_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "signal_type": "person_activity",
    "name": "Champions",
    "status": "active",
    "profile_urls": ["https://www.linkedin.com/in/satyanadella"],
    "activity_types": ["reactions", "comments"],
    "email_recipients": ["user@example.com"],
    "webhook_url": "https://yourapp.com/webhooks/signals"
  },
  "credit_used": 1
}
```

**signal\_id** `string`

Unique identifier for this signal. **Save this**: use it to update, add profiles to, or delete this signal.

**name** `string`

The signal's display name.

**profile\_urls** `array`

All profiles this signal tracks.

**activity\_types** `array`

What the signal reports: `"reactions"`, `"comments"`, or both.

***

## Credits

* **Creating a signal or adding profiles:** `1` credit per profile added.
* **Each run:** one [Person Activity](/api-reference/endpoints/people-activity) request per profile per activity type, billed at that endpoint's rate. Tracking both reactions and comments is two requests per profile per run. A very active person can need an extra page, which is one more request, capped at 3 pages per type per run.

Credits are charged to the API key the signal was created with.

***

## Webhook payload

Each delivery is a single `POST` with a JSON body. `job_id` is the signal's `signal_id`, and `job_name` is its name, so you can tell your signals apart.

### Baseline

Sent once per run in which profiles were tracked for the first time.

```json baseline theme={null}
{
  "event": "baseline",
  "user_email": "user@example.com",
  "signal_type": "person_activity",
  "job_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "job_name": "Champions",
  "profiles": [
    { "profile_url": "https://www.linkedin.com/in/satyanadella", "profile_name": "Satya Nadella" }
  ]
}
```

### New activity

One entry per reaction, comment, or reply, oldest first.

```json person_activity theme={null}
{
  "event": "person_activity",
  "user_email": "user@example.com",
  "signal_type": "person_activity",
  "job_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "job_name": "Champions",
  "changes": [
    {
      "event_id": "5b0c9d7e-2f4a-4c1b-9e3d-7a8b6c5d4e3f",
      "profile_url": "https://www.linkedin.com/in/satyanadella",
      "profile_name": "Satya Nadella",
      "signal_type": "reaction",
      "change_summary": "Liked a post by Ryan Roslansky",
      "confidence": null,
      "detected_at": "2026-09-18T08:00:12.204518+00:00",
      "change_data": {
        "activity_type": "reaction",
        "occurred_at": "2026-09-17T18:30:42.168Z",
        "reaction_type": "LIKE",
        "target": "post",
        "target_comment_author": null,
        "target_comment_url": null,
        "post_url": "https://www.linkedin.com/posts/ryanroslansky_ai-activity-7506405584091541505-fa6g",
        "post_urn": "urn:li:activity:7506405584091541505",
        "post_text": "AI is helping mathematicians make real progress on Navier-Stokes…",
        "post_author": {
          "name": "Ryan Roslansky",
          "url": "https://www.linkedin.com/in/ryanroslansky",
          "headline": "Executive Vice President at Microsoft"
        }
      }
    },
    {
      "event_id": "8e1f0a2b-3c4d-4e5f-a6b7-c8d9e0f1a2b3",
      "profile_url": "https://www.linkedin.com/in/satyanadella",
      "profile_name": "Satya Nadella",
      "signal_type": "comment",
      "change_summary": "Commented on a post by Kevin Scott: “Congratulations to the whole team on this milestone.”",
      "confidence": null,
      "detected_at": "2026-09-18T08:00:12.204518+00:00",
      "change_data": {
        "activity_type": "comment",
        "occurred_at": "2026-09-17T21:04:10.512Z",
        "comment_text": "Congratulations to the whole team on this milestone.",
        "comment_url": "https://www.linkedin.com/feed/update/urn:li:activity:7506512345678901234?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7506512345678901234%2C7506598765432109876%29",
        "comment_urn": "urn:li:comment:(activity:7506512345678901234,7506598765432109876)",
        "post_url": "https://www.linkedin.com/posts/kevinscott_milestone-activity-7506512345678901234-ab12",
        "post_urn": "urn:li:activity:7506512345678901234",
        "post_text": "Today we shipped…",
        "post_author": {
          "name": "Kevin Scott",
          "url": "https://www.linkedin.com/in/kevinscott",
          "headline": "CTO at Microsoft"
        }
      }
    }
  ]
}
```

### Fields

**changes\[].event\_id** `string`

Unique ID of this item. Use it to de-duplicate on your side.

**changes\[].signal\_type** `string`

`"reaction"`, `"comment"`, or `"reply"`.

**changes\[].change\_summary** `string`

One line describing the activity, such as `Liked a post by Ryan Roslansky` or `Replied to a comment on a post by Kevin Scott: "…"`. Comments and replies quote the start of the comment.

**changes\[].change\_data** `object`

**All activity types**

**activity\_type** `string`

`"reaction"`, `"comment"`, or `"reply"`.

**occurred\_at** `string`

ISO 8601 time the person reacted or commented, to the millisecond.

**post\_url** `string`

The post the activity is on.

**post\_urn** `string | null`

The post's LinkedIn URN.

**post\_text** `string | null`

The first 300 characters of the post.

**post\_author** `object | null`

The post's author: `name`, `url`, `headline`.

**Reactions**

**reaction\_type** `string`

`LIKE` · `EMPATHY` · `PRAISE` · `APPRECIATION` · `INTEREST` · `ENTERTAINMENT`

**target** `string`

`"post"`, or `"comment"` when the person reacted to a comment on the post.

**target\_comment\_author** `string | null`

Author of the comment reacted to, when `target` is `"comment"`.

**target\_comment\_url** `string | null`

Link to the comment reacted to, when `target` is `"comment"`.

**Comments and replies**

**comment\_text** `string | null`

The person's comment, up to 2,000 characters.

**comment\_url** `string | null`

Direct link to the comment.

**comment\_urn** `string | null`

The comment's LinkedIn URN.

`confidence` is always `null` for this signal.

***

## Managing the signal

Use [Update Signal](/api-reference/endpoints/signal-update) with `signal_type: "person_activity"`. Pass `signal_id` to choose the signal; it can be left out only when you have exactly one.

| Action | What it does |
| - | - |
| `add_profiles` / `remove_profiles` | Change the tracked people. New profiles take a baseline on their first run. |
| `update_activity_types` | Switch between reactions, comments, or both. Requires `activity_types`. |
| `rename` | Change the display name. Requires `name`. |
| `pause` / `resume` | Stop and restart the signal. |
| `update_webhook` / `update_emails` | Change where alerts go. |

To remove a signal completely, use [Delete Signal](/api-reference/endpoints/signal-delete).


# Person Engagement Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-person-engagement

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](/api-reference/webhooks).

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


# Update Signal
Source: https://docs.datamagnet.co/api-reference/endpoints/signal-update

POST https://api.datamagnet.co/api/v1/signal/update
Pause, resume, or modify an existing Datamagnet signal monitor, including its tracked profiles, keywords, target industries, or delivery webhook.

# Update Signal

Modify an existing signal monitor. Use the `action` field to specify what to change.

***

## job\_change / new\_post / person\_activity

Actions for profile-tracking signals. You can have several signals of one of these types; `signal_id` says which one to change.

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

`"job_change"`, `"new_post"`, or `"person_activity"`

**signal\_id** `string`

The signal to change, from [/signal/create](/api-reference/endpoints/signal-create) or [/signal/list](/api-reference/endpoints/signal-list). Can be left out only when you have exactly one signal of this type; with several, the request returns `400`.

**action** `string` *required*

| Action | Description |
| - | - |
| `pause` | Stop monitoring without deleting. Resume at any time. |
| `resume` | Reactivate a paused monitor. |
| `add_profiles` | Add new LinkedIn profiles to track. Requires `profile_urls`. New profiles take a baseline on their first run. |
| `remove_profiles` | Remove specific profiles. Requires `profile_urls`. Pauses automatically if all profiles are removed. |
| `update_webhook` | Change the webhook URL. Requires `webhook_url`. |
| `update_emails` | Replace the notification email list. Requires `additional_emails`. |
| `rename` | Change the signal's display name. Requires `name`. |
| `update_activity_types` | `person_activity` only. Change what is reported. Requires `activity_types`. |
| `update_schedule` | Change how often the signal runs. Requires at least one of `frequency`, `scheduled_time`, `scheduled_day`. |

**profile\_urls** `array`

Required for `add_profiles` and `remove_profiles`. LinkedIn profile URLs to add or remove.

**webhook\_url** `string`

Required for `update_webhook`. The new delivery URL.

**webhook\_secret** `string`

Optional with `update_webhook`. Updates the HMAC signing secret.

**additional\_emails** `array`

Required for `update_emails`. Replaces the current list. Your account email is always retained. Pass `[]` to remove all additional recipients.

**name** `string`

Required for `rename`. The new display name. Names don't need to be unique.

**activity\_types** `array`

Required for `update_activity_types`. `["reactions"]`, `["comments"]`, or `["reactions", "comments"]`.

**frequency** `string`

For `update_schedule`. `"every_hour"`, `"every_2hr"`, `"every_12hr"`, `"every_day"`, or `"every_week"`. Any other value returns `400`.

**scheduled\_time** `string`

For `update_schedule`. Time of day to run, `"HH:MM"` in UTC. With `every_12hr` the signal runs at this time and 12 hours later.

**scheduled\_day** `string`

For `update_schedule`. Day of the week to run, for `every_week` only.

**Credits:** `add_profiles` costs `1` credit per profile added. Other actions are free.

### Response

```json Pause / Resume theme={null}
{
  "message": "Signal paused successfully",
  "credit_used": 0
}
```

```json Add Profiles theme={null}
{
  "message": {
    "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
    "signal_type": "job_change",
    "status": "active",
    "profile_urls": [
      "https://linkedin.com/in/satyanadella",
      "https://linkedin.com/in/reidhoffman"
    ]
  },
  "credit_used": 1
}
```

```json Remove Profiles theme={null}
{
  "message": {
    "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
    "signal_type": "job_change",
    "profile_urls": ["https://linkedin.com/in/satyanadella"]
  },
  "credit_used": 0
}
```

```json Update Webhook theme={null}
{
  "message": "Webhook updated successfully",
  "credit_used": 0
}
```

```json Update Emails theme={null}
{
  "message": {
    "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
    "signal_type": "job_change",
    "email_recipients": ["user@example.com", "teammate@example.com"]
  },
  "credit_used": 0
}
```

```json Rename theme={null}
{
  "message": {
    "signal_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
    "signal_type": "job_change",
    "name": "Churned customers"
  },
  "credit_used": 0
}
```

```json Update Activity Types theme={null}
{
  "message": {
    "signal_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "signal_type": "person_activity",
    "activity_types": ["comments"]
  },
  "credit_used": 0
}
```

***

## keyword\_engagement / industry\_engagement / company\_engagement / person\_engagement

Engagement signals support multiple monitors per account. All actions require `signal_id` (returned when the signal was created).

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

`"keyword_engagement"`, `"industry_engagement"`, `"company_engagement"`, or `"person_engagement"`

**signal\_id** `string` *required*

The unique ID of the signal to update. Returned in the response when the signal was created.

**action** `string` *required*

| Action | Applies to | Description |
| - | - | - |
| `pause` | All engagement types | Stop the signal without deleting it. |
| `resume` | All engagement types | Reactivate a paused signal. |
| `update_targets` | All engagement types | Replace the signal's targets (keywords, industries, companies, or people). |
| `update_icp` | All engagement types | Replace the ICP filter configuration. |
| `update_webhook` | All engagement types | Change the webhook delivery URL. |
| `update_emails` | All engagement types | Replace the notification email list. |
| `update_keywords` | `keyword_engagement` only | Alias for `update_targets` on keyword signals. |
| `update_tracking_mode` | `person_engagement` only | Change whether to track posts, mentions, or both. |
| `rename` | All engagement types | Change the signal's display name. Requires `name`. |
| `update_schedule` | All engagement types | Change how often the signal runs. Requires at least one of `frequency`, `scheduled_time`, `scheduled_day`. |

### update\_targets

Replaces the primary targets for the signal. The required field depends on the signal type:

**keywords** `array`

**`keyword_engagement` only.** New list of seed keywords. Replaces the current keywords entirely.

```json theme={null}
["product-led growth", "B2B SaaS"]
```

**industries** `array`

**`industry_engagement` only.** New list of industry names. Unrecognised names are skipped and reported in `unresolved_industries`.

```json theme={null}
["software development", "financial services"]
```

**company\_urls** `array`

**`company_engagement` only.** New list of LinkedIn company URLs. Unresolvable URLs are skipped and reported in `unresolved_company_urls`.

```json theme={null}
["https://www.linkedin.com/company/salesforce/"]
```

**profile\_urls** `array`

**`person_engagement` only.** New list of LinkedIn profile URLs to monitor. Unresolvable URLs are skipped and reported in `unresolved_profile_urls`.

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

### update\_icp

**icp** `object`

Replaces the full ICP filter. See [ICP Filter Reference](/api-reference/endpoints/signal-keyword-engagement#icp-filter-reference) for all available fields. Pass `{}` to remove all filters.

```json theme={null}
{
  "job_titles": ["VP Sales", "Head of Revenue"],
  "seniority_levels": ["vp", "c_level"],
  "locations": ["United States"]
}
```

### update\_webhook

**webhook\_url** `string` *required*

The new delivery URL.

**webhook\_secret** `string`

Updates the HMAC signing secret.

### update\_emails

**additional\_emails** `array` *required*

Replaces the current recipient list. Your account email is always retained. Pass `[]` to remove all additional recipients.

### update\_tracking\_mode (`person_engagement` only)

**tracking\_mode** `string` *required*

`"posts"` — posts authored by the tracked person · `"mentions"` — posts mentioning them · `"both"` — both.

### rename

**name** `string` *required*

The new display name. Names don't need to be unique.

### update\_schedule

**frequency** `string`

`"every_hour"`, `"every_2hr"`, `"every_12hr"`, `"every_day"`, or `"every_week"`. Any other value returns `400`.

**scheduled\_time** `string`

Time of day to run, `"HH:MM"` in UTC. With `every_12hr` the signal runs at this time and 12 hours later.

**scheduled\_day** `string`

Day of the week to run, for `every_week` only.

### Response

```json Pause / Resume theme={null}
{
  "message": "Signal paused successfully",
  "credit_used": 0
}
```

```json update_targets (keyword_engagement) theme={null}
{
  "message": {
    "signal_id": "9f4a2c81-3b7e-4d12-a5f1-c8e0d9b2f3a4",
    "signal_type": "keyword_engagement",
    "keywords": ["product-led growth", "B2B SaaS"]
  },
  "credit_used": 0
}
```

```json update_targets (industry_engagement) theme={null}
{
  "message": {
    "signal_id": "3a1b9c42-7d2e-4f88-b6c1-e9f0a2d3c5b7",
    "signal_type": "industry_engagement",
    "industry_groups": [
      { "ids": [4], "label": "software development" }
    ],
    "unresolved_industries": ["saas tools"]
  },
  "credit_used": 0
}
```

```json update_targets (company_engagement) theme={null}
{
  "message": {
    "signal_id": "7c3e1f85-2a9d-4b6c-8e0f-d1a2b3c4d5e6",
    "signal_type": "company_engagement",
    "company_groups": [
      { "ids": [1441], "label": "Salesforce" }
    ]
  },
  "credit_used": 0
}
```

```json update_targets (person_engagement) theme={null}
{
  "message": {
    "signal_id": "b2d4f6a8-1c3e-5g7h-9i0j-k1l2m3n4o5p6",
    "signal_type": "person_engagement",
    "person_groups": [
      { "member_id": "ACoAABcd1234", "label": "Satya Nadella" }
    ]
  },
  "credit_used": 0
}
```

```json update_icp theme={null}
{
  "message": {
    "signal_id": "9f4a2c81-3b7e-4d12-a5f1-c8e0d9b2f3a4",
    "signal_type": "keyword_engagement",
    "icp": {
      "seniority_levels": ["vp", "c_level"],
      "locations": ["United States"]
    }
  },
  "credit_used": 0
}
```

```json update_tracking_mode theme={null}
{
  "message": {
    "signal_id": "b2d4f6a8-1c3e-5g7h-9i0j-k1l2m3n4o5p6",
    "signal_type": "person_engagement",
    "tracking_mode": "posts"
  },
  "credit_used": 0
}
```

```json update_emails theme={null}
{
  "message": {
    "signal_id": "9f4a2c81-3b7e-4d12-a5f1-c8e0d9b2f3a4",
    "signal_type": "keyword_engagement",
    "email_recipients": ["user@example.com", "teammate@example.com"]
  },
  "credit_used": 0
}
```

```json Rename theme={null}
{
  "message": {
    "signal_id": "9f4a2c81-3b7e-4d12-a5f1-c8e0d9b2f3a4",
    "signal_type": "keyword_engagement",
    "name": "CRM buyers, EMEA"
  },
  "credit_used": 0
}
```

***

## Notes

* Returns `404` if the signal does not exist or does not belong to your account.
* `update_emails` replaces the full recipient list — it does not append. Your account email is always retained.
* To permanently delete a signal, use [/signal/delete](/api-reference/endpoints/signal-delete).
* If the signal is running when you send a change, the response also has `"pending": true` and a `note`. The change is saved and takes effect when the current run finishes.


# Errors
Source: https://docs.datamagnet.co/api-reference/errors

Reference for Datamagnet API error codes and HTTP status responses, including authentication failures, rate limits, and validation errors.

# Errors

This guide covers what happens when something goes wrong while you work with the API, along with the status codes and error types you might encounter.

To tell if your request was successful, check the status code on the API response. If a response comes back unsuccessful, use the error type and error message to figure out what went wrong and debug before contacting support.

> [!NOTE]
>
> Before reaching out to support, double-check your code. Most reported errors turn out to be in the request itself rather than the API.

***

## Status codes

Here is a list of the different categories of status codes returned by the Datamagnet API. Use these to understand if a request was successful.

| Status Code | Description |
| - | - |
| **2xx** | A 2xx status code indicates a successful response. |
| **4xx** | A 4xx status code indicates a client error — something in your request needs to be corrected. |
| **5xx** | A 5xx status code indicates a server error on our side. These are rare. |

***

## Timeouts

Data is collected live when you request it, so response times vary: most calls answer in a few seconds, and a slow lookup can take longer. Every request is answered within about 80 seconds. A lookup that cannot finish in that time is returned as a failure you can retry (`"retryable": true` on company and person lookups, an error status on the other endpoints) and is **not charged**.

If your client gives up sooner, tell us how long it waits with the `X-Request-Timeout` header, in seconds:

```bash theme={null}
curl -X POST https://api.datamagnet.co/api/v1/post/reactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Request-Timeout: 30" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.linkedin.com/feed/update/urn:li:activity:7430615551086850048"}'
```

We then answer a few seconds before your timeout: with the data, or with an uncharged retryable failure if it is not ready. Without the header, a request your client abandons can still complete and be charged.

***

## Error types

When a request is unsuccessful, the Datamagnet API returns an error response with an error type and message. Use this information to understand what went wrong and how to fix it. Most error messages are designed to be actionable.

The Datamagnet API uses two error types, listed below.

### Error response format

```json Error response theme={null}
{
  "type": "api_error",
  "message": "No way this is happening!?",
  "documentation_url": "https://docs.datamagnet.co/errors/api_error"
}
```

### Error types

| Error Type | Description |
| - | - |
| **api\_error** | Indicates an error on the Datamagnet side. These are rare. |
| **invalid\_request** | Indicates an error in your request, such as missing or malformed parameters. |


# API Documentation
Source: https://docs.datamagnet.co/api-reference/introduction

Introduction to the Datamagnet API for collecting LinkedIn company, people, post, and signal data. Covers base URLs, authentication, and quotas.

# API Documentation

Use the Datamagnet API to access LinkedIn company, people, post, and signal data and integrate it directly into your product workflows.

> **[Quickstart](/api-reference/quickstart)**
>
> Get started with the Datamagnet API

> **[Register for API](https://datamagnet.co/auth/register)**
>
> Create an account to get your API key

## Getting started

To get started, [create an account](https://datamagnet.co/auth/register), then learn how to make requests for the type of profile you need (Company or Person) using the HTTP API.

[Get your API key →](https://datamagnet.co/auth/register)

## Guides

> **[Quickstart](/api-reference/quickstart)**
>
> Get started with the Datamagnet API

> **[Authentication](/api-reference/authentication)**
>
> Learn how to authenticate your API requests

> **[Errors](/api-reference/errors)**
>
> Read about the different types of errors returned by the API

## Resources

> **[People](/api-reference/endpoints/people)**
>
> Fetch a complete profile from a LinkedIn people URL and see the available attributes.

> **[Company](/api-reference/endpoints/company)**
>
> Fetch a complete profile from a LinkedIn company URL and see the available attributes.

> **[Funding Rounds](/api-reference/endpoints/funding-rounds)**
>
> Fetch funding round information from a company domain and see the available attributes.


# Quickstart
Source: https://docs.datamagnet.co/api-reference/quickstart

Get started with the Datamagnet API: create an account, generate an API key, configure your client, and make your first LinkedIn data request.

# Quickstart

This guide gets you set up and ready to use the Datamagnet API. It covers how to get started with an API client, how to make your first API request, and where to go next to take full advantage of the REST API.

> [!NOTE]
>
> Before you can make requests to the Datamagnet API, grab your API key from the dashboard under [Dashboard → API keys](https://datamagnet.co/app/api-keys).

## Making your first API request

Once you have your API key, you're ready to make your first call to the Datamagnet API. The example below sends a POST request to the People endpoint to fetch a complete LinkedIn profile from a LinkedIn people URL.

```bash cURL theme={null}
curl --request POST 'https://api.datamagnet.co/api/v1/person' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://linkedin.com/in/pratik-dani"
}'
```

```javascript JavaScript theme={null}
const token = "{your_token}";

const headers = new Headers();
headers.append("Authorization", `Bearer ${token}`);
headers.append("Content-Type", "application/json");

const data = {
  url: "https://linkedin.com/in/pratik-dani",
};

const requestOptions = {
  method: "POST",
  headers,
  body: JSON.stringify(data),
  redirect: "follow",
};

fetch("https://api.datamagnet.co/api/v1/person", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));
```

```python Python theme={null}
import requests
import json

token = "{your_token}"
url = "https://api.datamagnet.co/api/v1/person"

payload = {
  "url": "https://linkedin.com/in/pratik-dani"
}
headers = {
  'Authorization': f'Bearer {token}',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)
```

[Read the docs for the People endpoint →](/api-reference/endpoints/people)

## What's next?

You're now set up with an API client and have made your first request. Here are a few links that may be handy as you go further with the Datamagnet API:

* [Grab your API key from the Datamagnet dashboard](https://datamagnet.co/app/api-keys)
* [Check out the Company endpoint](/api-reference/endpoints/company)
* [Learn about the different error messages in Datamagnet](/api-reference/errors)


# Webhooks
Source: https://docs.datamagnet.co/api-reference/webhooks

Receive real-time Datamagnet signal notifications via HTTP POST to your server, including payload format, retry behavior, and signature verification.

# Webhooks

When a signal fires, Datamagnet sends an HTTP `POST` request to the `webhook_url` you configured when creating the signal.

## Registering a webhook

Pass a `webhook_url` when calling [/signal/create](/api-reference/endpoints/signal-create) or update it later via [/signal/update](/api-reference/endpoints/signal-update).

```json Example theme={null}
{
  "signal_type": "keyword_engagement",
  "keywords": ["sales intelligence"],
  "webhook_url": "https://yourapp.com/webhooks/signals",
  "webhook_secret": "your-hmac-secret"
}
```

***

## Payload format by signal type

Every delivery is one JSON object with a top-level `event` field:

| Signal types | `event` values |
| - | - |
| `job_change`, `new_post`, `person_activity` | `"baseline"` when profiles start being tracked, then the signal type (`"job_change"`, `"new_post"`, `"person_activity"`) when something changes |
| Engagement signals | The signal type, such as `"keyword_engagement"` |

### job\_change · new\_post · person\_activity

The first run for each profile records a baseline and sends a `baseline` event listing the profiles now tracked. After that, each run that finds changes sends **one** delivery with every change in `changes`.

`job_id` and `job_name` are the signal's `signal_id` and name, so you can tell apart several signals of one type. A profile tracked by two signals appears in a delivery from each.

```json baseline theme={null}
{
  "event": "baseline",
  "user_email": "user@example.com",
  "job_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
  "job_name": "Champions",
  "signal_type": "job_change",
  "profiles": [
    { "profile_url": "https://www.linkedin.com/in/satyanadella", "profile_name": "Satya Nadella" }
  ]
}
```

```json job_change theme={null}
{
  "event": "job_change",
  "user_email": "user@example.com",
  "job_id": "e7f1c2a4-9b3d-4c8e-a1f5-6d2b0c9e8a7f",
  "job_name": "Champions",
  "signal_type": "job_change",
  "changes": [
    {
      "event_id": "0c6f2e1a-8d4b-4f3a-9c7e-5b1a2d3e4f60",
      "profile_url": "https://www.linkedin.com/in/janedoe",
      "profile_name": "Jane Doe",
      "signal_type": "job_change",
      "change_summary": "Jane Doe started a new role as VP Sales at Acme Corp.",
      "confidence": 0.95,
      "detected_at": "2026-09-23T11:23:10.412345+00:00",
      "change_data": {
        "change_detected": true,
        "confidence": 0.95,
        "summary": "Jane Doe started a new role as VP Sales at Acme Corp.",
        "change_type": "new_job"
      }
    }
  ]
}
```

```json new_post theme={null}
{
  "event": "new_post",
  "user_email": "user@example.com",
  "job_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "job_name": "New Post Monitor",
  "signal_type": "new_post",
  "changes": [
    {
      "event_id": "7a6b5c4d-3e2f-4a1b-9c8d-7e6f5a4b3c2d",
      "profile_url": "https://www.linkedin.com/in/reidhoffman",
      "profile_name": "Reid Hoffman",
      "signal_type": "new_post",
      "change_summary": "Posted 2 new updates about AI agents and startup hiring.",
      "confidence": 0.95,
      "detected_at": "2026-09-23T11:23:10.412345+00:00",
      "change_data": {
        "change_detected": true,
        "confidence": 0.95,
        "summary": "Posted 2 new updates about AI agents and startup hiring.",
        "new_post_count": 2,
        "new_posts_link": [
          "https://www.linkedin.com/posts/reidhoffman_ai-agents-activity-7506405584091541505-fa6g",
          "https://www.linkedin.com/posts/reidhoffman_hiring-activity-7506398765432101234-bc34"
        ],
        "topics": ["AI agents", "startup hiring"]
      }
    }
  ]
}
```

For `person_activity`, `changes` holds one entry per reaction, comment, or reply. See the [Person Activity guide](/api-reference/endpoints/signal-person-activity#webhook-payload) for its payload.

***

### Engagement signals

All four engagement signal types — `keyword_engagement`, `industry_engagement`, `company_engagement`, and `person_engagement` — share the same webhook payload structure. The only difference is the `signal_type` value and the meaning of `signal_keyword`.

```json keyword_engagement example theme={null}
{
  "event": "keyword_engagement",
  "user_email": "user@example.com",
  "signal_type": "keyword_engagement",
  "run_stats": {
    "keywords_processed": 5,
    "total_raw": 142,
    "after_dedup": 89,
    "after_icp": 14,
    "flame_1": 4,
    "flame_2": 7,
    "flame_3": 3
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/johndoe",
      "profile_name": "John Doe",
      "headline": "VP Sales at Acme Corp",
      "signal_keyword": "sales intelligence",
      "engagement_type": "comment",
      "engagement_post_url": "https://linkedin.com/posts/someauthor_activity-7123456789",
      "engagement_link": "https://linkedin.com/posts/someauthor_activity-7123456789?commentUrn=urn%3Ali%3Acomment%3A123",
      "comment_text": "This is exactly the problem we've been trying to solve. Would love to chat.",
      "post_excerpt": "Most sales teams are flying blind. Here's how the top 1% use intent data to close 3x faster...",
      "post_author": "Jane Smith",
      "lead_score": 3,
      "icp_score": 0.87,
      "signal_score": 0.91,
      "detected_at": "2026-04-20T09:15:00Z"
    },
    {
      "linkedin_url": "https://linkedin.com/in/janedoe",
      "profile_name": "Jane Doe",
      "headline": "CRO at TechCo",
      "signal_keyword": "outbound prospecting",
      "engagement_type": "like",
      "engagement_post_url": "https://linkedin.com/posts/someauthor_activity-9876543210",
      "engagement_link": "https://linkedin.com/posts/someauthor_activity-9876543210",
      "comment_text": null,
      "post_excerpt": "Cold outbound is not dead. Here's the 5-step framework we used to book 200 meetings last quarter...",
      "post_author": "Bob Jones",
      "lead_score": 2,
      "icp_score": 0.74,
      "signal_score": 0.68,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}
```

```json company_engagement example theme={null}
{
  "event": "company_engagement",
  "user_email": "user@example.com",
  "signal_type": "company_engagement",
  "run_stats": {
    "companies_processed": 3,
    "total_raw": 78,
    "after_dedup": 51,
    "after_icp": 9,
    "flame_1": 2,
    "flame_2": 5,
    "flame_3": 2
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/alexchen",
      "profile_name": "Alex Chen",
      "headline": "Director of Sales at StartupXYZ",
      "signal_keyword": "Salesforce",
      "engagement_type": "comment",
      "engagement_post_url": "https://linkedin.com/posts/salesforce_activity-1234567890",
      "engagement_link": "https://linkedin.com/posts/salesforce_activity-1234567890?commentUrn=urn%3Ali%3Acomment%3A456",
      "comment_text": "We switched from Salesforce last year and the ROI has been incredible.",
      "post_excerpt": "Announcing Salesforce Einstein AI — the future of CRM is here. Watch our keynote...",
      "post_author": "Salesforce",
      "lead_score": 3,
      "icp_score": 0.91,
      "signal_score": 0.88,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}
```

```json industry_engagement example theme={null}
{
  "event": "industry_engagement",
  "user_email": "user@example.com",
  "signal_type": "industry_engagement",
  "run_stats": {
    "industries_processed": 2,
    "total_raw": 95,
    "after_dedup": 62,
    "after_icp": 11,
    "flame_1": 3,
    "flame_2": 6,
    "flame_3": 2
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/morganlee",
      "profile_name": "Morgan Lee",
      "headline": "VP of Revenue at FinTechCo",
      "signal_keyword": "Financial Services",
      "engagement_type": "like",
      "engagement_post_url": "https://linkedin.com/posts/fintech-author_activity-5678901234",
      "engagement_link": "https://linkedin.com/posts/fintech-author_activity-5678901234",
      "comment_text": null,
      "post_excerpt": "The fintech landscape in 2026: open banking is no longer optional for survival...",
      "post_author": "Sarah Williams",
      "lead_score": 2,
      "icp_score": 0.82,
      "signal_score": 0.65,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}
```

```json person_engagement example theme={null}
{
  "event": "person_engagement",
  "user_email": "user@example.com",
  "signal_type": "person_engagement",
  "run_stats": {
    "persons_processed": 2,
    "total_raw": 44,
    "after_dedup": 31,
    "after_icp": 7,
    "flame_1": 1,
    "flame_2": 4,
    "flame_3": 2
  },
  "leads": [
    {
      "linkedin_url": "https://linkedin.com/in/taylorwong",
      "profile_name": "Taylor Wong",
      "headline": "Head of Revenue Operations at ScaleUp Inc",
      "signal_keyword": "John Doe",
      "engagement_type": "comment",
      "engagement_post_url": "https://linkedin.com/posts/johndoe_activity-2345678901",
      "engagement_link": "https://linkedin.com/posts/johndoe_activity-2345678901?commentUrn=urn%3Ali%3Acomment%3A789",
      "comment_text": "Totally agree John — pipeline velocity is the metric nobody talks about but everyone should.",
      "post_excerpt": "After running sales teams for 10 years, here's the one metric I wish I'd tracked from day one...",
      "post_author": "John Doe",
      "lead_score": 3,
      "icp_score": 0.93,
      "signal_score": 0.95,
      "detected_at": "2026-04-20T09:15:00Z"
    }
  ]
}
```

***

## Engagement signal payload fields

Missed a delivery, or want the history? [/signal/leads](/api-reference/endpoints/signal-leads) returns your stored leads with these same fields, on request.

### Top level

**event** `string`

Same as `signal_type`.

**user\_email** `string`

The account email that owns the signal.

**signal\_type** `string`

One of `"keyword_engagement"` · `"company_engagement"` · `"industry_engagement"` · `"person_engagement"`.

**run\_stats** `object`

Aggregated counts for this run. The group count key varies by signal type:

| Signal type | Group count key |
| - | - |
| `keyword_engagement` | `keywords_processed` |
| `industry_engagement` | `industries_processed` |
| `company_engagement` | `companies_processed` |
| `person_engagement` | `persons_processed` |

All types include `total_raw`, `after_dedup`, `after_icp`, `flame_1`, `flame_2`, `flame_3`.

**leads** `array`

Qualified leads sorted by `lead_score` descending. Each object contains the fields below.

### Per-lead fields

**linkedin\_url** `string`

The LinkedIn profile URL of the person who engaged.

**profile\_name** `string`

Full name of the engager.

**headline** `string`

Current LinkedIn headline of the engager.

**signal\_keyword** `string`

The search term or group label that surfaced this lead.

* **keyword\_engagement** — the keyword that matched (e.g. `"sales intelligence"`)
* **company\_engagement** — the company label (e.g. `"Salesforce"`)
* **industry\_engagement** — the industry label (e.g. `"Financial Services"`)
* **person\_engagement** — the monitored person's label (e.g. `"John Doe"`)

**engagement\_type** `string`

How the person engaged with the post. Either `"like"` (or a specific reaction type such as `"celebrate"`, `"support"`) or `"comment"`.

**engagement\_post\_url** `string`

URL of the LinkedIn post the person engaged with.

**engagement\_link** `string`

Deep link to the specific engagement. For comments, this links directly to the comment. For likes, same as `engagement_post_url`.

**comment\_text** `string | null`

The text of the comment left by the engager. `null` for likes and reactions — only populated when `engagement_type` is `"comment"`.

**post\_excerpt** `string | null`

First 300 characters of the post the engager interacted with. Gives context about the content that triggered the signal. `null` if the post text could not be retrieved.

**post\_author** `string | null`

Full name of the person or page who authored the post. `null` if the author could not be retrieved.

**lead\_score** `integer`

Overall lead quality score from 1 to 3.

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

`composite = 0.5 × icp_score + 0.5 × signal_score`

**icp\_score** `number`

ICP fit score between 0.0 and 1.0. Reflects how well the lead matches the configured ICP filters.

**signal\_score** `number`

Intent signal score between 0.0 and 1.0. Based on engagement type (comment = 1.0, like = 0.7), post recency (decays over 14 days), and keyword specificity.

**detected\_at** `string`

ISO 8601 timestamp of when the lead was scored.

***

## job\_change · new\_post · person\_activity payload fields

### Top level

**event** `string`

`"baseline"`, or the signal type when there are changes.

**user\_email** `string`

The account email that owns the signal.

**job\_id** `string`

The signal's `signal_id`.

**job\_name** `string`

The signal's display name.

**signal\_type** `string`

`"job_change"`, `"new_post"`, or `"person_activity"`.

**profiles** `array`

`baseline` events only. Each newly tracked profile: `profile_url`, `profile_name`.

**changes** `array`

Change events only. One entry per change, with the fields below.

### Per-change fields

**event\_id** `string`

Unique ID of this change. Use it to de-duplicate on your side.

**profile\_url** `string`

The tracked LinkedIn profile.

**profile\_name** `string`

Full name of the tracked person.

**signal\_type** `string`

`"job_change"` or `"new_post"`; for `person_activity`, `"reaction"`, `"comment"`, or `"reply"`.

**change\_summary** `string`

One or two sentences describing the change.

**confidence** `number | null`

How sure the detection is, from 0.0 to 1.0. `null` for `person_activity`.

**detected\_at** `string`

ISO 8601 time the change was detected.

**change\_data** `object`

Details of the change.

**job\_change**

**summary** `string`

Same as `change_summary`.

**confidence** `number`

Same as `confidence`.

**change\_type** `string`

`"new_job"`, `"promotion"`, or `"same_company"`.

**change\_detected** `boolean`

Always `true`.

**new\_post**

**summary** `string`

Same as `change_summary`.

**confidence** `number`

Same as `confidence`.

**new\_post\_count** `integer`

How many new posts were found.

**new\_posts\_link** `array`

URLs of the new posts.

**topics** `array`

Main topics of the new posts.

**change\_detected** `boolean`

Always `true`.

**person\_activity**

See the [Person Activity guide](/api-reference/endpoints/signal-person-activity#fields).

When the change could not be analysed in detail, `change_data` also has `"_llm_fallback": true` and a shorter, generic summary. The change itself is real.

***

## Verifying webhook signatures

If you set a `webhook_secret`, every request includes an `X-Datamagnet-Signature` header: `sha256=` followed by the hex HMAC-SHA256 of the raw request body, signed with your secret. The same value is also sent as `X-Signature-256`.

```python Python theme={null}
import hmac
import hashlib
from flask import request

def verify_signature(secret: str) -> bool:
    signature = request.headers.get("X-Datamagnet-Signature", "")
    body = request.get_data()
    expected = "sha256=" + hmac.new(
        key=secret.encode("utf-8"),
        msg=body,
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
```

```javascript Node.js theme={null}
const crypto = require('crypto')

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader || '')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}
```

```php PHP theme={null}
function verifySignature(string $secret, string $rawBody, string $signatureHeader): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signatureHeader);
}
```

> [!WARNING]
>
> Always use a timing-safe comparison (`hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js) to prevent timing attacks.

***

## Responding to webhooks

Your endpoint must return a `2xx` status within **10 seconds**. If it times out or returns an error, Datamagnet retries the same payload:

| Attempt | When (approximately) |
| - | - |
| 1 | Immediately |
| 2 | 5 minutes later |
| 3 | 30 minutes later |
| 4 | 2 hours later |
| 5 | 8 hours later |
| 6 | 24 hours later |
| 7 | 48 hours later |

A `400`, `401`, `403`, or `404` response means the endpoint is misconfigured, so it is retried once and then dropped. Use `event_id` (profile signals) to ignore a change you already processed.

Acknowledge immediately and process asynchronously to avoid timeouts:

```python Python (Flask) theme={null}
from flask import request, jsonify
from threading import Thread

@app.route('/webhooks/signals', methods=['POST'])
def handle_signal():
    payload = request.json
    Thread(target=process_signal, args=(payload,)).start()
    return jsonify({"received": True}), 200
```


# Changelog: April 2026
Source: https://docs.datamagnet.co/changelog/april-2026

April 2026 updates to the Datamagnet API, including reliability improvements to the People endpoint and refinements to Post Search filters.

**April 30, 2026**

## Week of April 30

Here's everything that shipped this week.

### Improvement: People endpoint reliability

Additional reliability work on the [People](/api-reference/endpoints/people) endpoint. Profile data parsing has been tuned further to improve consistency on edge-case profiles.

**April 29, 2026**

## Week of April 29

Here's everything that shipped this week.

### Improvement: Post Search refinements

The [Post Search](/api-reference/endpoints/post-search) endpoint has been tuned for more reliable results. Search handling and response formatting have been refined to improve consistency across keyword, content type, and author filters.

### Improvement: People endpoint reliability

Continued reliability work on the [People](/api-reference/endpoints/people) endpoint. Profile parsing has been further tuned to reduce inconsistencies on edge-case profiles.

**April 28, 2026**

## Week of April 28

Here's everything that shipped this week.

### Improvement: People endpoint stability

Further reliability work on the [People](/api-reference/endpoints/people) endpoint and shared response handling. Profile parsing and field normalization have been tuned again to reduce inconsistencies on edge-case profiles.

**April 27, 2026**

## Week of April 27

Here's everything that shipped this week.

### Improvement: People endpoint refinements

Additional reliability work on the [People](/api-reference/endpoints/people) endpoint. Profile data parsing has been tuned further to improve consistency on edge-case profiles.

**April 26, 2026**

## Week of April 26

Here's everything that shipped this week.

### Improvement: People profile reliability

Continued refinements to the [People](/api-reference/endpoints/people) endpoint to produce more consistent results across edge-case profiles. Field normalization and parsing have been hardened further on top of last week's accuracy improvements.

### Bug fixes

* Resolved several edge cases that could affect response consistency on the [People](/api-reference/endpoints/people) endpoint.

**April 24, 2026**

## Week of April 24

Here's everything that shipped this week.

### New: AI agent discovery and webMCP

Datamagnet is now discoverable by AI agents and model-context clients. A set of standards-based discovery endpoints lets agents find the API, its OAuth metadata, and ready-to-use tools without custom wiring.

* Agents can load `lookup_person`, `lookup_company`, `get_pricing`, and `get_api_docs` directly from the Datamagnet website.
* Use the [API reference](/api-reference/introduction) and [authentication guide](/api-reference/authentication) to get started.

### New: Public OpenAPI 3.0 specification

A full OpenAPI 3.0 spec for the Datamagnet API is now published, covering People, Company, Posts, Signals, ICP Search, and account utilities. Import it into Postman, generate client SDKs, or use it with any OpenAPI-compatible tool.

See the [API reference](/api-reference/introduction) for the complete endpoint list.

### Improvement: LinkedIn person data accuracy

The [People](/api-reference/endpoints/people) endpoint has been updated with more reliable profile parsing and cleaner field normalization. Expect more consistent results for edge-case profiles.

### Bug fixes

* Hardened LinkedIn profile URL extraction to handle additional URL variants without erroring.
* Fixed response formatting issues that could surface inconsistent fields on a small number of [People](/api-reference/endpoints/people) responses.

**April 22, 2026**

## Week of April 22

Here's everything that shipped this week.

### New: ICP search

Search for people and companies using powerful ICP filters — job title, seniority, industry, location, company size, revenue, technology stack, and more. All values are human-readable strings, no IDs required.

* [ICP People Search](/api-reference/endpoints/icp-people-search) — find people matching your ideal customer profile
* [ICP Company Search](/api-reference/endpoints/icp-company-search) — find companies by industry, headcount, revenue, and more
* [ICP Suggest](/api-reference/endpoints/icp-suggest) — typeahead suggestions for filter fields like company name, job title, and location

See the full [ICP Search Filter Reference](/api-reference/endpoints/icp-search-filters) for all supported filter values.

### New: People Search endpoint

A new [People Search](/api-reference/endpoints/people-search) endpoint lets you search for LinkedIn people by keyword, job title, company name, and more. Returns profile details including headline, location, and LinkedIn URL.

### New: industry, company, and person engagement signals

Three new signal types let you monitor LinkedIn engagement from different angles and surface qualified leads automatically:

* [Industry Engagement](/api-reference/endpoints/signal-industry-engagement) — track posts from companies in your target industries and capture the people who engage with them
* [Company Engagement](/api-reference/endpoints/signal-company-engagement) — monitor posts from specific companies and surface leads from their audience
* [Person Engagement](/api-reference/endpoints/signal-person-engagement) — follow posts and mentions from specific people (competitors, champions, influencers) and score the leads who interact

Each signal type supports ICP filtering, lead scoring (1–3), webhook delivery, and email digests — just like keyword engagement signals.

### Update: ICP search filter changes

The `postal_code` filter has been removed from [ICP People Search](/api-reference/endpoints/icp-people-search) and [ICP Company Search](/api-reference/endpoints/icp-company-search). Use the `location` filter with city, region, or country values instead.

### Improvement: LinkedIn profile URL handling

The [People](/api-reference/endpoints/people) and [People Activity](/api-reference/endpoints/people-activity) endpoints now return clearer error messages when an invalid LinkedIn profile URL is provided. Profile URL extraction is also more robust, reducing failures on edge-case URL formats.

**April 14, 2026**

## Signals API

You can now monitor LinkedIn activity in real time with the new [Signals API](/api-reference/endpoints/signal-create). Create signals to track:

* **Job changes** — get notified when target profiles change roles or companies
* **New posts** — know the moment a prospect publishes on LinkedIn
* **Keyword engagement** — surface qualified leads who engage with posts matching your keywords, automatically scored against your ICP

Manage your signals with [create](/api-reference/endpoints/signal-create), [list](/api-reference/endpoints/signal-list), [update](/api-reference/endpoints/signal-update), and [delete](/api-reference/endpoints/signal-delete) endpoints.

**April 14, 2026**

## Keyword engagement signals

The new [Keyword Engagement](/api-reference/endpoints/signal-keyword-engagement) signal type monitors LinkedIn for posts matching your keywords, extracts people who liked or commented, filters them against your ICP, and scores each lead from 1 to 3 based on seniority and engagement type.

**April 14, 2026**

## Webhooks

Receive real-time notifications when your signals fire. [Webhooks](/api-reference/webhooks) deliver `job_change` and `new_post` events to your server via HTTP POST, with HMAC-SHA256 signature verification and automatic retries.

**April 14, 2026**

## Cookbooks

New ready-to-use guides showing how to combine Datamagnet APIs for common sales workflows:

* [Champion Tracking](/cookbooks/champion-tracking) — track when past customers move to new companies
* [Competitor Hijack](/cookbooks/competitor-hijack) — surface leads engaging with competitor content
* [VIP Engagement Radar](/cookbooks/executive-intelligence) — get notified when target executives post on LinkedIn
* [Signal Workflows](/cookbooks/workflows) — 9 ready-to-run workflows across all signal types

**April 12, 2026**

## Post Search and Company Search

Two new search endpoints are now available:

* [Post Search](/api-reference/endpoints/post-search) — search LinkedIn posts by keyword, content type, date range, and author title
* [Company Search](/api-reference/endpoints/company-search) — search LinkedIn companies by keyword, size, industry, and hiring status

**April 16, 2026**

## Zoho CRM extension

Datamagnet now integrates with Zoho CRM, letting you sync LinkedIn intelligence directly into your CRM workflows.


# Changelog: August 2026
Source: https://docs.datamagnet.co/changelog/august-2026

August 2026 Datamagnet API release notes: a flattened Job Details response, richer job and company fields, and rendered job description HTML.

**August 12, 2026**

## Week of August 12

### Job Details: flattened response and new fields

[Job Details](/api-reference/endpoints/job-details) now returns the posting directly under `data`, rather than splitting it across `job_info`, `company_info`, `apply_details` and `hiring_team` sections. The hiring company stays nested under `company_info`; everything else — including the apply counts and links — sits alongside the posting's own fields.

```json theme={null}
{
  "data": {
    "title": "Generative AI Engineer",
    "location": "Noida, Uttar Pradesh, India",
    "total_applies": 0,
    "application_url": "https://www.linkedin.com/job-apply/4443378596",
    "company_info": { "name": "HCLTech", "staff_count": 257915 }
  }
}
```

**Migrating:**

| Before | Now |
| - | - |
| `data.job_info.title` | `data.title` |
| `data.apply_details.total_applies` | `data.total_applies` |
| `data.company_info.name` | `data.company_info.name` (unchanged) |
| `data.hiring_team` | `data.hiring_team` (present only when requested) |
| `data.source`, `data.source_url` | removed |

`hiring_team` is now absent unless `include_hiring_team` was set and the section was returned, instead of being `null`. Check for the key rather than for a `null` value.

### New fields

* `standardized_title` — LinkedIn's normalized title for the role, so postings titled "Gen AI Engineer" and "Generative AI Engineer" group together
* `closed_at` — when a posting stopped accepting applications
* `applicant_tracking_system` — the ATS behind the posting, when named
* `description_html` — the job description as ready-to-render HTML, with paragraphs, lists and bold preserved

`company_info` now fills fields that were previously often empty: `headquarters`, `company_id`, `followers` and `company_size`.

### Format changes

* Timestamps are ISO 8601 UTC with a trailing `Z`, e.g. `"2026-07-21T13:36:54Z"`
* `company_size` is a plain bracket: `"51-200"`, `"10001+"`
* `workplace_types` values are always `ONSITE`, `REMOTE` or `HYBRID`
* Fields with no value are always `null`, never an empty string
* Multi-word industries stay whole: `["IT Services and IT Consulting"]`, not split on "and"


# Changelog: July 2026
Source: https://docs.datamagnet.co/changelog/july-2026

July 2026 Datamagnet API release notes: the new Job Details endpoint, People profile enrichment flags, and Company insights for interests, similar profiles, recommendations, and headcount/hiring trends.

**July 31, 2026**

## Week of July 31

### New: Job Details endpoint

[Job Details](/api-reference/endpoints/job-details) returns a single LinkedIn job posting from its ID or URL: title, full description, location, employment type, seniority, workplace type, salary when published, posting and expiry dates, application counts and the hiring company.

```bash theme={null}
POST /api/v1/jobs/detail
{"job_id": "4444390169"}
```

Two optional sections, each an extra `1` credit charged only when it returns data:

* `include_company` — the hiring company's description, employee count, specialities, headquarters address and cover image
* `include_hiring_team` — the job poster and recruiters listed on the posting, with profile URLs and photos

A base request costs `1` credit; both flags together cost `3`. A section that could not be retrieved comes back as `null` and is not charged, and failed requests are never charged.

Every response returns the same set of fields whichever options you send — a field that a given request cannot fill is `null` rather than absent, so parsing code never has to branch.

**July 25, 2026**

## Week of July 25

### Standardized endpoint paths

All data endpoints now live directly under `/api/v1/` — for example `POST /api/v1/person`, `POST /api/v1/company`, `POST /api/v1/post/comments`, and `POST /api/v1/salesnavigator/search`. The documentation and OpenAPI specs now reference the new paths everywhere.

**No action required:** every previous path (e.g. `POST /api/v1/linkedin/person`) remains fully supported as a permanent alias, with identical request and response formats, authentication, and credit costs. Existing integrations continue to work unchanged.

**July 4, 2026**

## Week of July 4

### New: People profile enrichment flags

The [People](/api-reference/endpoints/people) endpoint now supports seven optional enrichment flags, each appending an additional data section to the profile response for an extra 2 credits (charged only on success):

* `company_interest` — companies the profile follows
* `top_voices_interest` — LinkedIn Top Voices the profile follows
* `group_interest` — LinkedIn Groups the profile belongs to
* `school_interest` — schools the profile follows
* `newsletter_interest` — LinkedIn Newsletters the profile is subscribed to
* `similar_profiles` — profiles similar to this one
* `recommendations_data` — full profile bundle plus recommendations given/received

All enrichment requests retry automatically on transient failures. If an enrichment fails after retries, the base profile response still succeeds and the field contains a generic error instead of failure details — no credit is charged for a failed enrichment.

### New: Company insights flag

The [Company](/api-reference/endpoints/company) endpoint now supports an optional `company_insights` flag, appending an `insights` section to the response for an extra 10 credits (charged only on success): headcount trends, hiring trends, notable alumni, job openings by function, and median employee tenure. Retried automatically on transient failures; a failed insights request returns a generic error in `insights` and is not charged.


# Changelog: May 2026
Source: https://docs.datamagnet.co/changelog/may-2026

May 2026 Datamagnet API release notes: new Profiles Search endpoint, standardized employee_count field, and People, Company, and Post reliability fixes.

**May 31, 2026**

## Week of May 31

Here's everything that shipped this week.

### New: Profiles Search endpoint

A new `/profiles/search` endpoint is now available, letting you query our LinkedIn profile store directly by indexed fields with a flat per-request credit cost. Use it for fast profile lookups without running a full enrichment. It uses the same authentication as the rest of the API.

### Update: Standardized `employee_count` field

The company employee field is now consistently returned as `employee_count` across all responses. If you previously relied on the `employee` field, update your integrations to use `employee_count`. See the [Company](/api-reference/endpoints/company) endpoint.

### Improvement: Person endpoint reliability

Multiple rounds of refinements to the [People](/api-reference/endpoints/people) endpoint to improve profile parsing consistency, including more robust handling of edge-case profiles and cleaner field normalization.

### Improvement: Company endpoint reliability

The [Company](/api-reference/endpoints/company) endpoint has been tuned for steadier results on edge-case company profiles, with better handling of missing or malformed fields.

### Improvement: Post and search reliability

Reliability work on the [Post](/api-reference/endpoints/post) and search-related endpoints, including more resilient retries and helpers behind the scenes. Expect fewer transient failures on high-volume requests.

### Bug fixes

* Resolved inconsistencies in [People](/api-reference/endpoints/people) responses on certain edge-case profiles.
* Fixed cases where [Company](/api-reference/endpoints/company) responses could return inconsistent field shapes.

**May 24, 2026**

## Week of May 24

Here's everything that shipped this week.

### New: Signals dashboard with access control

The Signals dashboard has been refreshed with a cleaner UI and now supports access control, making it easier to manage who in your team can view and edit signals. Manage your signals with the [Signals API](/api-reference/endpoints/signal-create).

### Update: Signal frequency options

The shortest signal polling intervals have been removed to keep signal runs reliable and predictable. Existing signals on longer intervals are unaffected. See the [signal create](/api-reference/endpoints/signal-create) reference for current frequency options.

### Improvement: Person endpoint coverage

The [People](/api-reference/endpoints/people) endpoint now uses the canonical `linkedin.com` base for profile lookups and surfaces "people also viewed" data on user profiles, giving you richer context on every lookup.

### Improvement: Filter and post handling

Internal post processing and filter handling have been refined, improving result consistency for [Post Search](/api-reference/endpoints/post-search) and ICP filter queries.


# Changelog: October 2026
Source: https://docs.datamagnet.co/changelog/october-2026

October 2026 Datamagnet API release notes: mentions and sorting on post comments, complete long comment threads, more profile data in every Person response, and fixes to recommendation counts and dates.

**October 5, 2026**

## Week of October 5

### Fixed: reactions on reposted posts

[Post Reactions](/api-reference/endpoints/post-reactions) returned no reactions for a post that a company page had reposted, although the post had reactions. It now returns them. [Company Posts](/api-reference/endpoints/company-posts) also returns `original_post_url` for a repost, and `original_post_urn` now names the original post and not the repost.

### Improved: no charge for the empty last page

[People Activity](/api-reference/endpoints/people-activity) is no longer charged for the empty page that ends a list. The cursor stays set until that page, so loop until a page is empty or has no cursor. A page with few items is not necessarily the last one.

### Improved: people search

* [People Search](/api-reference/endpoints/people-search) removes repeated people within a page and returns `duplicates_removed`, so a page can hold fewer than 50 people. Use `has_more` to decide whether to continue. `total` is an upper bound, and the same person can still appear on two pages, so de-duplicate by `urn`.
* [ICP People Search](/api-reference/endpoints/icp-people-search) results include `company_id`, `is_current` and `started_on` for the role shown.

### Docs

* `include_extra` and `skills` on [Person](/api-reference/endpoints/people) are deprecated and ignored. They never changed the data or the price, and they are not charged.
* A company page's posts go back about 12 months, as noted on [Company Posts](/api-reference/endpoints/company-posts).

**October 4, 2026**

## Week of October 4

### New: mentions on comments and replies

Every comment and reply now has a `mentions` array that lists the people and companies it tags, in the same shape as post mentions: `entity_urn`, `name` and `type` (`"profileMention"` or `"companyMention"`). It is empty when nobody is tagged.

* [Post Comments](/api-reference/endpoints/post-comments) returns `mentions` on every comment and on every reply in `top_replies`.
* [People Activity](/api-reference/endpoints/people-activity) returns them as `comment.mentions` on comment and reply items. The top-level `mentions` on those items still describes the post.

### New: sort comments

[Post Comments](/api-reference/endpoints/post-comments) accepts `sort`: `"recent"` for newest first, or `"relevance"`. Any other value returns a `400` and is not charged.

### Improved: comments are newest first by default

Without `sort`, comments now come newest first. Before, the order varied from post to post. To pick up only new comments, read from page 1 and stop at the first comment you already have.

### Improved: send the cursor back as `cursor`

[Post Comments](/api-reference/endpoints/post-comments), [Post Reactions](/api-reference/endpoints/post-reactions) and [Post Reposts](/api-reference/endpoints/post-reposts) now accept the `cursor` from the previous response as `cursor` as well as `page`. Before, a `cursor` input was ignored and the first page was returned again. If you send both, `page` is used.

### Fixed: long threads ended early

Some long threads stopped after the first page, or after a few hundred comments, with a `cursor` of `null` while `total` showed more. Paging with the `cursor` now returns the whole thread. On a 414-comment thread it returns 412 comments; `total` counts two that LinkedIn does not return.

**October 3, 2026**

## Week of October 3

### New: more data in the Person response

[Person](/api-reference/endpoints/people) returns more of what a LinkedIn profile carries. Every key is present on every response; a value that is not available is empty or `null`.

* **Test scores:** `test_scores`, with name, score and date.
* **Profile:** `is_top_voice`, `show_follower_count`, `geo_urn` for the profile's location, and the school of the top education in `current_school_id` and `current_school_urn`.
* **Roles:** `position_urn`, `geo_urn`, `geo_id`, `total_duration` (for example `4 yrs 10 mos`), `position_group_urn` and `position_group_id` to group the roles held at one company, `is_current`, and the `skills` attached to the role.
* **Education:** `education_urn`, `is_current`, and the `skills` line LinkedIn shows under an entry.
* **LinkedIn ids on every list entry:** publications, projects, volunteering, honors, organizations, patents and courses each carry their own URN. Honors, courses, projects and organizations also carry the `position_urn` or `education_urn` of the role or school they are attached to.
* **Recommendations:** `last_modified_at`.

### Improved: the same entry shape in every list

`recommendations_received`, `recommendations_given`, `also_viewed`, `websites`, `contact_info`, `updates` and `featured` now have one documented entry shape on every request. The [People page](/api-reference/endpoints/people) lists every key, including nested ones, with its type and when it can be `null`, and its example response contains every key.

* `address` is a string or `null`, never an object.
* A role dated by year only has a start and end date in the same `M-YYYY` form as every other role, with month `0`: `0-2023`.
* Language, volunteering, education and project details that were sometimes returned empty are now filled when LinkedIn has them, and language proficiency uses LinkedIn's standard values such as `FULL_PROFESSIONAL`.
* `similar_profiles` returns a plain list of `{name, url, headline, location, profile_picture, urn}` for every account, and every entry carries all six keys.

### Fixed

* `received_recommendation_count` in `recommendations_data` returned the number of recommendations given instead of received.
* A certification that expires returned the expiry date as its issue date.
* The birth year is returned when LinkedIn shows one.

### Documented

The `company_interest_page`, `group_interest_page`, `school_interest_page` and `newsletter_interest_page` parameters, which choose the page of each interest list, are now on the [People page](/api-reference/endpoints/people), and every enrichment field is described down to its nested keys.


# Changelog: September 2026
Source: https://docs.datamagnet.co/changelog/september-2026

September 2026 Datamagnet API release notes: the new person_activity signal, several named signals per type, and a Person response with the same fields on every request.

**September 25, 2026**

## Week of September 25

### New: fetch your stored leads

The new [/signal/leads](/api-reference/endpoints/signal-leads) endpoint returns the leads your engagement signals have found, so you can read past leads instead of only receiving them by webhook or email. Filter by signal, lead score, keyword, engagement type, name or headline, and date, sort by date or score, and page through your full history.

It is free, and it returns the lead fields your webhooks carry, plus a stable `id`, the `signal_id`, and `icp_match_details`.

**September 23, 2026**

## Week of September 23

### New: person\_activity signal

The new [`person_activity`](/api-reference/endpoints/signal-person-activity) signal tells you when a person you track reacts to or comments on any post on LinkedIn. Each alert includes the post, its author, and the comment text. Choose reactions, comments, or both with `activity_types`.

### Several signals of one type, with names

You can now run several `job_change`, `new_post`, or `person_activity` signals, for example one for champions and one for churned customers. Each has its own profiles, baseline, and alerts.

* [/signal/create](/api-reference/endpoints/signal-create) returns a `signal_id` for every signal type. Pass `new_signal: true` to start another signal of a type you already have, or `signal_id` to add profiles to a specific one.
* Every signal type accepts an optional `name`, and the new `rename` action on [/signal/update](/api-reference/endpoints/signal-update) changes it.
* [/signal/update](/api-reference/endpoints/signal-update) and [/signal/delete](/api-reference/endpoints/signal-delete) take `signal_id` for profile signals. Without it, a request still means your only signal of that type, so existing integrations keep working.
* Webhooks for profile signals now include `job_id` and `job_name`.

### Improved: signals run on schedule

Signals now start at their scheduled time. Before, busy periods could delay a run by several hours.

### Docs: webhook signatures and retries

The [webhook signature](/api-reference/webhooks#verifying-webhook-signatures) header is `sha256=` followed by the hex digest; the verification examples now include the prefix. The [retry schedule](/api-reference/webhooks#responding-to-webhooks) now shows all 7 attempts, and the payload reference shows the fields that `job_change` and `new_post` webhooks actually send.

**September 19, 2026**

## Week of September 19

### Person: the same response shape on every request

[Person](/api-reference/endpoints/people) now returns the same set of fields, in the same order, on every request. Every entry in a list (`experience`, `education`, `certification`, `publication`, `project`, `volunteering`, `honors_and_awards`, `organizations`, `patents`, `language`, `courses`) has the same keys. Before, a field could be present on one request and missing on the next for the same profile. That no longer happens, including for profiles served from cache.

A field with no value is still present:

* `""` for text
* `[]` for lists
* `null` where the value is not known

Check a field's value, not whether the key exists.

### Breaking changes

| Field | Before | Now |
| - | - | - |
| `followers`, `connections` | sometimes `0` when the count was not available | `null` when the count is not available |
| `job_still_working` (profile and `experience[]`) | `false` for a role with no dates | `null` for a role with no start or end date; `true` / `false` only when the dates are known |
| `certification[].startedOn` | `startedOn` | renamed to `started_on` (same object) |
| `publication[].published_on` | sometimes an object `{ "year", "month", "day" }` | always the string `"M/D/YYYY"` (`""` when there is no month); the object is now in `published_on_date` |
| `honors_and_awards[]`, `organizations[]`, `patents[].inventors[]`, `project[].contributors[]`, `courses[]` | sometimes camelCase keys (`issuedOn`, `positionHeld`, `firstName`, …) and `multiLocale*` copies | snake\_case keys only (`issued_on`, `position_held`, `first_name`, …); `multiLocale*` removed |
| `location_state`, `location_county` | sometimes `"City, State"` | `location_state` is the state or region; `location_county` is always `""` |
| `experience[].company_id` | `"0"` for a company without a LinkedIn page | `""` |
| `experience[].job_location_country` | could end in `" · Remote"` | the country only; the workplace type is in the new `workplace_type` |
| `honors_and_awards[].issuer` | sometimes `"Issued by …"` | the issuer's name only |
| `project[].description` | could start with `"Associated with …"` | that line is in `associated_with` |
| `volunteering[].is_current_position` | `true` for an entry with no dates | `true` only when the entry has a start date and no end date |

### New fields

**Profile**

* **Location:** `address_without_country`, `address_country_only`, `country_code` (ISO 3166 alpha-2, e.g. `"US"`) and `location_city`. The existing `location`, `country`, `address_with_country` and `address` are now present on every response too.
* **Industry:** `industry` and `industry_name` (always the same value), plus `industry_urn`.
* **Pictures:** `profile_pictures` / `avatar_all_dimensions` and `background_pictures` / `background_picture_all_dimensions`. Both forms are always present and list the same images.
* **Other fields now present on every response:** `total_experiences`, `primary_locale`, `is_hiring`, `is_memorialized`, `show_premium_badge`, `courses`, `updates`, `contact_info`. A flag that could not be read is `null`, not `false`.
* **Birthday:** `birthday` is filled with the month and day when the profile shows them.

**Experience**

* `workplace_type`: `"On-site"`, `"Remote"` or `"Hybrid"`, when the role shows it.
* `company_username` and `company_urn` on every role.
* When a company is known to us, `company_id`, `company_username` and `company_url` identify it the same way on every request. `company_url` takes the form `https://www.linkedin.com/company/<name>/`.
* `company_headcount_range` always uses the form `"11-50 employees"`.

**Other sections**

* `education[].university_urn`.
* `publication[]`: `published_on_date` (`{ "day", "month", "year" }`, `0` when unknown), `publishing_date` (`"Nov 11 2014"`) and `authors`.
* `project[]`: `start`, `end`, `date`, `url`, `contributors`, `associated_with` and `subtitle`.
* `volunteering[]`: `started_on`, `ended_on`, `start_date`, `end_date`, `duration`, `is_current_position`, `description`, `cause`, and `organization` alongside `company_name`.
* `certification[]`: both naming styles are always filled, `issuer` / `authority` / `company_name`, `issued_on` / `started_on` and `expires_on` / `end_date`.
* `organizations[]`: `name` / `title`, `position_held` / `subtitle`, `start` and `end`.
* `honors_and_awards[].issued_on`.

### Fixes

* Education dates written with months (e.g. `"Sep 2023 - Present"`) were being dropped. They are now returned, including the month.
* Experience lists for profiles with a long work history are more complete.
* `use_cache: "never"` now always fetches the profile fresh. Before, repeating the same request within a few minutes could return the previous response.
* A role whose only location was its workplace type (e.g. "Remote") now gets the profile's location, like any other role without one.


# The Champion Tracker
Source: https://docs.datamagnet.co/cookbooks/champion-tracking

Track when power users and decision-makers change jobs using job_change signals so your team can re-engage them at their new companies.

# The Champion Tracker

In B2B, your best future customers are your past happy customers. When a "Champion" (a decision-maker who used your product at a previous company) starts a new role, they are highly likely to buy your solution again.

## The strategy

1. **Identify:** Export a list of LinkedIn profiles for your "Closed-Won" champions from your CRM.
2. **Monitor:** Use Datamagnet to watch for job title or company changes.
3. **Act:** When a change is detected, your sales team reaches out with a "Congrats" and a demo offer.

## How to run it

Submit a `POST` request to the `/signal/create` endpoint with your list of champion URLs.

```json theme={null}
{
  "signal_type": "job_change",
  "profile_urls": [
    "https://linkedin.com/in/champion-profile-1",
    "https://linkedin.com/in/champion-profile-2"
  ],
  "additional_emails": ["sales-ops@yourcompany.com"],
  "webhook_url": "https://your-crm.com/webhooks/job-change"
}
```


# Competitor Hijack
Source: https://docs.datamagnet.co/cookbooks/competitor-hijack

Surface qualified leads who engage with competitor content or industry pain points on LinkedIn using keyword and company engagement signals.

# Competitor Hijack

Intent data is most powerful when it’s fresh. This workflow identifies people engaging with posts about your competitors or specific industry problems, then filters them to ensure they fit your Ideal Customer Profile (ICP).

## The strategy

1. **Define Keywords:** Use competitor names or phrases like "CRM problems" or "Sales automation".
2. **Set ICP:** Filter out anyone who isn't a decision-maker (e.g., only "Director" or "VP" level).
3. **Score:** Datamagnet scores these leads (1–3) based on their seniority and the type of engagement (comments score higher than likes).

## How to run it

Create a keyword signal with a specific ICP filter.

```json theme={null}
{
  "signal_type": "keyword_engagement",
  "keywords": ["competitor-name", "sales intelligence", "outbound help"],
  "icp": {
    "job_titles": ["VP Sales", "Head of Revenue"],
    "seniority_levels": ["vp", "c_level", "director"],
    "locations": ["United States", "United Kingdom"],
    "company_size": ["51 - 200", "201 - 500"]
  },
  "webhook_url": "https://your-platform.com/api/leads"
}
```


# The VIP Engagement Radar
Source: https://docs.datamagnet.co/cookbooks/executive-intelligence

Get notified the moment a high-value prospect or executive posts on LinkedIn, so your team can react with timely outreach and personalized replies.

# The VIP Engagement Radar

Standard automated outreach is dead. High-conversion "Social Selling" requires you to engage with prospects where they are active. This workflow ensures you are always the first to comment on a target executive's post.

## The strategy

1. **Target:** Create a list of "Top 50" dream accounts.
2. **Listen:** Subscribe to their new posts using Datamagnet.
3. **Engage:** Set up a Slack notification via Webhook so your SDRs can leave a thoughtful, relevant comment within minutes of the post going live.

## How to run it

Send a `POST` request to initialize the monitor. Datamagnet merges new URLs into your existing monitor automatically.

```json theme={null}
{
  "signal_type": "new_post",
  "profile_urls": [
    "https://linkedin.com/in/target-ceo-1",
    "https://linkedin.com/in/target-vp-2"
  ],
  "webhook_url": "https://hooks.slack.com/services/T000/B000/XXXX"
}
```