LinkedIn Conversions API Export Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

The LinkedIn Conversions API (CAPI) connector enables server-side tracking and measurement of conversion events for B2B marketing campaigns. By integrating directly with LinkedIn's Events Manager, this connector helps businesses measure campaign performance and optimize ad delivery more effectively across LinkedIn's network of 900M+ global professionals.

Key capabilities:

• Web Events: Server-side tracking to complement pixel data for enhanced B2B lead generation measurement, including form submissions, content downloads, and demo requests
• Lead Generation Events: Direct integration for tracking qualified leads and downstream conversion events in complex B2B sales cycles
• Professional Targeting Data: Support for tracking professional identifiers and attributes like job titles, company names, and industry segments
• Data Validation: Automated event validation and formatting to LinkedIn CAPI specifications, ensuring accurate tracking of professional conversion events

This server-side integration provides more reliable conversion tracking and improved B2B campaign performance measurement compared to client-side solutions alone, particularly valuable for businesses targeting professional audiences and measuring longer sales cycles.

Prerequisites

• Basic knowledge of Treasure Data, including the TD Toolbelt.
• Basic knowledge of LinkedIn Ads.

Limitations & Known Issues

• Event Time Restrictions: Events older than 90 days (based on event_time) will be skipped during processing
• Event time validations use UTC timezone for epoch conversions

Create a New Connection

Before running your query, you must create and configure the data connection on the TD Console. As part of the data connection, you provide authentication to access the integration. Complete the following steps.

1. Open TD Console.
2. Navigate to Integrations Hub > Catalog.
3. Search for and select LinkedIn Ads Conversions API. Hover over the icon and selectCreate Authentication.
4. Ensure that the Credentials tab is selected, and then select Click here to start the OAuth authentication flow. After completing the authentication, a new OAuth connection will be created and available in the dropdown.
5. Select Continue to create a new connection.

Configure a Query Result for Export

The TD Console supports multiple ways to export data. Follow these steps to export data from the Data Workbench.

1. Navigate to Data Workbench > Queries.
2. Select New Query, and define your query.
3. Select Export Results to configure the data exporting.
4. Select an existing LinkedIn CAPI authentication or create a new one described previously
5. Select Done.

Connector Configuration Parameters

Configuration with Conversion Rule ID

Configuration with New Conversion Rule

Detailed Guide for Query Result Data Specs

For uploading event data to LinkedIn, you need to build a data export query that includes a combination of default and custom fields that adhere to LinkedIn CAPI’s guidelines. For default fields, ensure that the column names match those listed in the “Field/Column-Level Specifications” section. The connector automatically normalizes the column names to match LinkedIn’s required format, so you do not need to worry about case sensitivity.

For example, for the default field “conversionHappenedAt,” the column name in your export query can be written in any case, such as “CONVERSIONHAPPENEDAT,” “conversionhappenedat,” or “ConversionHappenedAt.” The connector will standardize the column name to “conversionHappenedAt” to align with LinkedIn CAPI’s requirements.

To successfully upload or modify user profile data to LinkedIn CAPI, you must construct an export query that adheres to specific data specifications. These specifications are divided into two levels:

• Export Query Specifications (or Dataset-level data specs): This section describes the requirements and rules that apply to your entire query result dataset, such as the presence of required fields and data validation rules that span multiple fields.
• Field/Column-Level Specifications: This section details the requirements and rules for individual fields/columns in your dataset, such as data types and formats for each field.

Export Query Specifications

Field or Column-Level Specifications

Standard Event Parameters

User Identification Parameters

User Information Parameters

Conversion Value Parameters

Special Field Handling

Handling Date-Time

The integration can handle values cast as timestamps or in ISO-8601 date-time string format for date-time custom field columns. When using ISO-8601 date-time strings, ensure the value includes the letter “Z” at the end to allow the connector to detect and convert the date-time value into a Unix time value as required by LinkedIn Ads CAPI’s API contract.

Examples for Handling Date-Time Custom Field Columns

1. Casting as Timestamp

• Create a column of type string in the source data table:

ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;

• Insert date-time value strings into that column:

INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28'),(2, '2024-08-28 15:30:00'),(3, '2024-08-28T15:30:00');

• Cast the column value as timestamp:

SELECT id, CAST(date_time_field AS timestamp) AS date_time_field FROM source_data_table;

2. Using ISO-8601 Date-Time String

• Create a column of type string in the source data table:

ALTER TABLE source_data_table ADD COLUMN date_time_field VARCHAR;

• Insert date-time value strings into that column, ensuring they are formatted as ISO-8601 with a “T” separator and “Z” at the end:

INSERT INTO source_data_table (id, date_time_field)VALUES(1, '2024-08-28T00:00:00Z'),(2, '2024-05-28T15:30:00.123Z'),(3, '2024-02-28T15:30:00Z');

• Use the column directly in the query:

SELECT id, date_time_field FROM source_data_table;

Activate a Segment in Audience Studio

You can also send segment data to the target platform by creating an activation in the Audience Studio.

1. Navigate to Audience Studio.
2. Select a parent segment.
3. Open the target segment, right-mouse click, and then select Create Activation.
4. In the Details panel, enter an Activation name and configure the activation according to the previous section on Configuration Parameters.
5. Customize the activation output in the Output Mapping panel.

• Attribute Columns
  • Select Export All Columns to export all columns without making any changes.
  • Select + Add Columns to add specific columns for the export. The Output Column Name pre-populates with the same Source column name. You can update the Output Column Name. Continue to select + Add Columnsto add new columns for your activation output.
• String Builder
  • + Add string to create strings for export. Select from the following values:
    • String: Choose any value; use text to create a custom value.
    • Timestamp: The date and time of the export.
    • Segment Id: The segment ID number.
    • Segment Name: The segment name.
    • Audience Id: The parent segment number.

6. Set a Schedule.

• Select the values to define your schedule and optionally include email notifications.

7. Select Create.

(Optional) Export Integration Using the CLI

You can also use CLI (Toolbelt) to export results to LinkedIn Conversion CAPI.

You need to specify the information for export to your LinkedIn server using the *--result option of*the td query command. For more information about the *td query*command, refer to this article.

The format of the option is JSON, and the general structure is as follows.

out:
  type: linkedin_ads_conversion_api
  client_id: your client id
  client_secret: your client secret
  refresh_token: your refresh token
  ad_account_id: your ad account id
  conversion_rule_id: your conversion rule id
  use_conversion_rule_id: true
  skip_invalid_records: true

Parameters

Example for Usage

OAuth authentication

td query --result '{"type":"linkedin_ads_conversion_api","client_id":"client_id","client_secret":"client_secret","refresh_token":"refresh_token,"ad_account_id":"ad_account_id", "conversion_rule_id":conversion_rule_id,"use_conversion_rule_id":true,"skip_invalid_records":true}' -d sample_database "select conversion,conversionhappenedat,currencycode,amount,sha256_email,linkedin_first_party_ads_tracking_uuid,acxiom_id,oracle_moat_id,firstName,title,lastName,companyname,countrycode,externalids as externalIds,lead,eventid from conversion" -T presto

Related articles

Other Configurations

• The Result Export can be scheduled to periodically upload data to a target destination.
• All import and export integrations can be added to a TD Workflow. The td data operator can export a query result to a specified integration. For more information, see Reference for Treasure Data Operators.
• API Document: Microsoft Conversion API
• Authorization Code Flow: Microsoft Authorization Code Flow (3-legged OAuth)