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

# LinkedIn Connector

> Deliver people and company audiences to LinkedIn Matched Audiences for ad targeting

The LinkedIn Connector delivers audience data to LinkedIn Campaign Manager as Matched Audiences, either lists of people or lists of companies, for targeting in LinkedIn ad campaigns.

## Overview

The connector delivers two kinds of LinkedIn audience. A people audience matches on email addresses and Android advertising IDs. A company audience matches on company names, domains, and LinkedIn company pages, for account-based targeting. For either kind you can create a new audience in one of your ad accounts or deliver into one that already exists. An opt-out removes people or companies from every audience of its kind that your connections deliver to.

## Guides

> [card] [Setting Up the LinkedIn Connector](https://docs.narrative.io/guides/connectors/linkedin/setting-up.md)
>
> Install the connector, connect a profile, and reconnect it before the grant expires

> [card] [Connecting an Opt-Out Dataset](https://docs.narrative.io/guides/connectors/connecting-an-opt-out-dataset.md)
>
> Remove opted-out people and companies from LinkedIn audiences

## Requirements

### Account access

* A LinkedIn Campaign Manager ad account that isn't a test account and hasn't been closed
* A LinkedIn account with a role other than Viewer on that ad account. Connecting a profile asks LinkedIn for the `r_ads` and `rw_dmp_segments` permissions

### Supported identifiers for people audiences

Your data must include at least one of these identifier types, mapped to the corresponding Rosetta Stone attribute:

| Identifier Type | Rosetta Stone Attribute |
| - | - |
| SHA256 hashed email | [`sha256_hashed_email`](https://app.narrative.io/platform/rosetta-stone/attributes/sha256_hashed_email) |
| Hashed email (SHA256) | [`hashed_email`](https://app.narrative.io/platform/rosetta-stone/attributes/hashed_email) (type `sha256_email`) |
| Email | [`raw_email`](https://app.narrative.io/platform/rosetta-stone/attributes/raw_email) (automatically normalized and hashed) |
| Android Advertising ID (GAID) | [`android_advertising_id`](https://app.narrative.io/platform/rosetta-stone/attributes/android_advertising_id) |
| Narrative ID | [`narrative_id`](https://app.narrative.io/platform/rosetta-stone/attributes/narrative_id) |

The connector removes whitespace from a raw email and lowercases it before hashing it. Dots and `+` tags stay as they are.

> [!NOTE]
>
> Hashed emails must use SHA256. A `hashed_email` value of another type, such as SHA-1 or MD5, is skipped during delivery. See [Hashing PII for Upload](https://docs.narrative.io/guides/ingestion/hashing-pii.md) for formatting requirements.

> [!WARNING]
>
> The connector doesn't match people on name, phone number, or Apple IDFA. A row that carries none of the identifiers above delivers nothing.

### Supported identifiers for company audiences

Your data must include at least one of these identifier types. Each one can identify a company by itself:

| Identifier Type | Rosetta Stone Attribute |
| - | - |
| Company name | [`company_name`](https://app.narrative.io/platform/rosetta-stone/attributes/company_name) |
| Company website domain | [`company_website_domain`](https://app.narrative.io/platform/rosetta-stone/attributes/company_website_domain) |
| Company email domain | [`company_email_domain`](https://app.narrative.io/platform/rosetta-stone/attributes/company_email_domain) |
| LinkedIn company page URL | [`linkedin_company_page_url`](https://app.narrative.io/platform/rosetta-stone/attributes/linkedin_company_page_url) |
| LinkedIn organization URN | [`linkedin_organization_urn`](https://app.narrative.io/platform/rosetta-stone/attributes/linkedin_organization_urn) |

A mapped [`postal_address`](https://app.narrative.io/platform/rosetta-stone/attributes/postal_address) narrows the match with its city, region, postal code, and country. An address can't identify a company by itself, so a row with only an address delivers nothing.

Company identifiers reach LinkedIn as plain text, not hashed. The connector trims each value, and sends only the first value of each identifier type in a row and the row's first address.

## Managing profiles

Each profile carries its own LinkedIn grant. The **Profiles** tab lists every profile with its **Status**, and a profile's page shows the rest:

* **Status**: **Connected**, **Expiring**, **Expired**, or **Not Connected**. Only Connected and Expiring profiles deliver audiences, list them on the **Audiences** tab, and make opt-outs available. [Setting Up the LinkedIn Connector](https://docs.narrative.io/guides/connectors/linkedin/setting-up.md#reconnect-before-the-grant-expires) explains each status and how to reconnect.
* **Profile status**: whether the profile is **Enabled** or **Disabled**.
* **LinkedIn grant expires**: the date the grant expires. It reads **LinkedIn grant expired** once the date has passed.
* **Ad accounts**: the ad accounts the grant reaches, with **Refresh** to read them from LinkedIn again. Shown while the profile is Connected or Expiring.
* **Delete profile**: removes the profile.

## Delivering audiences

When you connect a dataset to the LinkedIn Connector, you pick a **Profile** and, when the dataset fits more than one, a **Connection type**. A dataset mapped to people identifiers is offered the people types, and one mapped to company identifiers is offered the company types. To connect a dataset of opted-out people or companies instead, see [Opt-outs](#opt-outs).

| Connection type | What it does |
| - | - |
| New People Audience | Creates a people audience in one of the profile's ad accounts |
| Existing People Audience | Delivers into a people audience already in one of the profile's ad accounts |
| New Company Audience | Creates a company audience in one of the profile's ad accounts |
| Existing Company Audience | Delivers into a company audience already in one of the profile's ad accounts |

### New People Audience

| Setting | Description |
| - | - |
| Audience name | Name for the audience created in LinkedIn, pre-filled from the dataset name. Required |
| Description | Description for the audience in LinkedIn, pre-filled from the dataset description. Optional |
| Ad account | The ad account the audience is created under. Selected for you when the profile reaches only one. Required |
| Dataset write mode | **Append** or **Overwrite**, pre-filled from the source dataset's write mode. See [Write modes](#write-modes) |
| Member TTL (days) | Append only. Removes a member this many days after the dataset last delivered it (1–28). Leave empty to keep members until an opt-out removes them |
| Deliver all data | Whether to also deliver data written to the dataset in the 30 days before the connection is created. Unchecked, only data written after the connection is configured is delivered |

### Existing People Audience

| Setting | Description |
| - | - |
| Ad account | The ad account that holds the audience. Required |
| Audience | The existing people audience to deliver into. Required |
| Dataset write mode | **Append** only. Overwrite needs an audience that Narrative created |
| Deliver all data | Whether to also deliver data written to the dataset in the 30 days before the connection is created. Unchecked, only data written after the connection is configured is delivered |

### New Company Audience

| Setting | Description |
| - | - |
| Audience name | Name for the audience created in LinkedIn, pre-filled from the dataset name. Required |
| Description | Description for the audience in LinkedIn, pre-filled from the dataset description. Optional |
| Ad account | The ad account the audience is created under. Selected for you when the profile reaches only one. Required |
| Deliver all data | Whether to also deliver data written to the dataset in the 30 days before the connection is created. Unchecked, only data written after the connection is configured is delivered |

### Existing Company Audience

| Setting | Description |
| - | - |
| Ad account | The ad account that holds the audience. Required |
| Audience | The existing company audience to deliver into. Required |
| Deliver all data | Whether to also deliver data written to the dataset in the 30 days before the connection is created. Unchecked, only data written after the connection is configured is delivered |

The **Audience** list offers audiences of the matching kind that were built through LinkedIn's API, such as the ones Narrative creates. An audience uploaded to Campaign Manager as a CSV file isn't offered, because LinkedIn accepts only CSV uploads into it.

### Write modes

The dataset write mode decides what happens to an audience's existing members when a new delivery arrives. Company audiences and existing people audiences always append.

| Mode | Available on | What each delivery does | Members leave the audience when |
| - | - | - | - |
| Append | Every connection type | Adds the delivered identifiers to the audience | An opt-out removes them |
| Append with a member TTL | New People Audience | Adds the delivered identifiers and restarts each one's TTL clock | They have not appeared in a delivery for the TTL's number of days, or an opt-out removes them |
| Overwrite | New People Audience | Replaces the audience's members with the rows in the delivery: identifiers missing from it are removed, then new ones are added | A delivery arrives without them, or an opt-out removes them |

Use Overwrite with an overwrite dataset, where each delivery is the complete, current audience. Each delivery carries one new dataset snapshot. On an overwrite dataset, every snapshot is the full dataset, so an Overwrite connection keeps the audience matching the dataset. On an append dataset, every snapshot holds only the newly added rows, so an Overwrite connection shrinks the audience to the latest batch at each delivery.

> [!NOTE]
>
> Creating a new audience fails when the ad account already holds LinkedIn's maximum of 1,000 audiences built through its API. The connection's error says so.

## Audience status in LinkedIn

A successful delivery in Narrative means the identifiers reached LinkedIn. LinkedIn then matches them to its members or companies, and the **Audiences** tab on the connector page shows how far each audience has got.

Pick a **Profile**, an **Ad account**, and an **Audience type** (**People** or **Companies**). Only Connected and Expiring profiles are offered. The tab lists the audiences in that ad account that were built through LinkedIn's API, so an audience uploaded as a CSV file doesn't appear.

| Column | What it shows |
| - | - |
| Name | The audience's name in LinkedIn |
| Status | LinkedIn's status for the audience, described below |
| Matched | LinkedIn's matched count for the audience. Shows "—" until LinkedIn has matched it |
| Audience size | The audience's size in LinkedIn. Shows "—" until LinkedIn has matched it |
| Audience ID | LinkedIn's ID for the audience, the one an Existing People Audience or Existing Company Audience connection takes. Campaign Manager shows a different ID for the same audience |

| Status | Meaning |
| - | - |
| Ready | LinkedIn has finished processing the audience |
| Building | LinkedIn is still processing the audience |
| Unknown | LinkedIn reported no status for the audience |
| Unavailable | Narrative couldn't read the status from LinkedIn. Hover over it for LinkedIn's error message |

LinkedIn can report other statuses, which the tab shows in LinkedIn's own words. Click **Refresh statuses** to read every status from LinkedIn again.

## API connection settings

A connection's `quick_settings` pick the interface and set how the connection delivers. The fields depend on the interface. The interface's JSON Schema is authoritative; retrieve it with [List app interfaces](https://docs.narrative.io/api-reference/apps/list-app-interfaces.md).

### New people audience (`user_audience_new`)

The connector creates the audience in LinkedIn when you create the connection.

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `ad_account_id` | The ad account the audience is created in | An ad account the profile reaches | None. Required |
| `audience_name` | The audience's name in LinkedIn | Any string | None. Required |
| `audience_description` | The audience's description in LinkedIn | Any string | None |
| `dataset_write_mode` | How each delivery changes the audience: `append` adds members, `overwrite` replaces them | `append`, `overwrite` | `append` |
| `ttl_days` | With `append`, removes a member this many days after the last delivery that included it | 1 to 28 | None. Members stay until an opt-out removes them |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `true` |

### Existing people audience (`user_audience_existing`)

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `ad_account_id` | The ad account that holds the audience | An ad account the profile reaches | None. Required |
| `audience_id` | The audience to deliver to | The **Audience ID** of a people audience in that ad account, built through LinkedIn's API | None. Required |
| `dataset_write_mode` | How each delivery changes the audience | `append`. A connection with `overwrite` is rejected | `append` |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `true` |

### New company audience (`company_audience_new`)

The connector creates the audience in LinkedIn when you create the connection. Company audiences take no write mode or member TTL, because every delivery appends.

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `ad_account_id` | The ad account the audience is created in | An ad account the profile reaches | None. Required |
| `audience_name` | The audience's name in LinkedIn | Any string | None. Required |
| `audience_description` | The audience's description in LinkedIn | Any string | None |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `true` |

### Existing company audience (`company_audience_existing`)

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `ad_account_id` | The ad account that holds the audience | An ad account the profile reaches | None. Required |
| `audience_id` | The audience to deliver to | The **Audience ID** of a company audience in that ad account, built through LinkedIn's API | None. Required |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `true` |

### People and company opt-outs (`user_opt_out`, `company_opt_out`)

| Field | What it does | Allowed values | Default |
| - | - | - | - |
| `historical_data_enabled` | Whether the connection also delivers data already in the dataset | `true`, `false` | `true` |

A connection created over the API without `dataset_write_mode` uses `append`. The connection form in Narrative pre-fills the source dataset's write mode instead.

### Existing and new rows

A connection delivers every snapshot written to the dataset after the connection is created. The `historical_data_enabled` quick setting decides whether the connection also delivers data that was already in the dataset when you created it:

* With `historical_data_enabled` set to `true`, the connection first delivers data already in the dataset, then keeps delivering new snapshots as they land.
* With `historical_data_enabled` set to `false`, the connection delivers only snapshots written after it was created.

How far back the first delivery reaches depends on the connector, and each connector's guide states it.

For LinkedIn, `historical_data_enabled` delivers the dataset's data from the 30 days before the connection was created. After that, each new snapshot is delivered as it lands.

## Audience membership duration

Membership duration is how long a delivered identifier remains active in the destination audience before the destination platform expires it. It is distinct from the dataset's [retention policy](https://docs.narrative.io/concepts/primitives/dataset-retention-policies.md) (which governs data stored in Narrative) and the interface's [refresh window](https://docs.narrative.io/concepts/data-activation/connector-interfaces.md) (which governs how stale the source dataset may get).

| Field | Value |
| - | - |
| Configurable | Yes, on new people audiences with the Append write mode |
| Setting | Member TTL (days) |
| Range | 1–28 days, or leave blank for no expiration |
| Default | No expiration. Members stay until an opt-out removes them |
| Applies | Per member. Each delivery that includes an identifier restarts its clock |

Narrative enforces the TTL itself. A daily job removes the members the dataset has not delivered within the TTL, so a member can stay up to one day longer than the TTL. Company audiences, existing audiences, and Overwrite connections have no TTL. See [Write modes](#write-modes).

## Opt-outs

The **Opt Out Configuration** tab on the connector page connects a dataset of opted-out people or companies to LinkedIn. Set **Opt out** to **People** or **Companies** before you connect the dataset:

* **People**: removes the dataset's people from every LinkedIn people audience your company's connections deliver to, across all of your LinkedIn profiles. The dataset needs at least one of the [people identifiers](#supported-identifiers-for-people-audiences).
* **Companies**: removes the dataset's companies from every LinkedIn company audience your company's connections deliver to. The dataset needs at least one of the [company identifiers](#supported-identifiers-for-company-audiences).

The opt-out connection itself names no ad account and no audience. To connect an opt-out dataset, follow [Connecting an Opt-Out Dataset](https://docs.narrative.io/guides/connectors/connecting-an-opt-out-dataset.md).

> [!NOTE]
>
> You need at least one connected profile before **Connect opt out dataset** becomes available. Each removal is sent with the grant of the profile that owns the audience, so a removal from the audiences of a profile whose grant has expired fails. Keep every profile that delivers audiences connected.

***

## Related content

> [card] [Data Activation Overview](https://docs.narrative.io/concepts/data-activation/overview.md)
>
> Understand how connectors deliver data

> [card] [Hashing PII](https://docs.narrative.io/guides/ingestion/hashing-pii.md)
>
> Prepare identifiers for LinkedIn

> [card] [Structuring Audiences](https://docs.narrative.io/guides/activation/audience-strategies.md)
>
> Organize datasets for delivery

> [card] [Schema Incompatibility Errors](https://docs.narrative.io/reference/errors/dataset-schema-connector-incompatible.md)
>
> Resolve errors when a dataset schema doesn't match a connector

> [card] [LinkedIn Connector API](https://docs.narrative.io/api-reference/linkedin/profiles/list-profiles.md)
>
> Profiles, ad accounts, audiences, and connection settings forms on the connector host


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