Conversion Tracking

Conversion tracking gives advertisers confidence that an ad product delivers a measurable return on investment. This includes better ad reporting based on tracked conversions coming from impressions, the ability to optimize campaigns through better targeting and impression delivery, and more efficient media planning and budget allocation through impression tracking and attribution.

Permissions

Whether set as a default permission in your app settings or requested specifically via the scope argument during your authentication process, you will need to request the rw_ads member permission in order for your application to successfully make these API calls to LinkedIn. If you are using legacy permissions, please refer to this page for requesting legacy permissions.

Requirements

See the following setup requirements to perform conversion tracking:

  1. Register website domain(s) using the Insight Tag Domains API.
  2. Get the Insight Tag associated with the advertiser account.
  3. Deploy the Insight Tag JavaScript snippet in a common header or footer on the advertiser's site. This is your tracking code, and is unique to the advertiser account.
  4. Create one or more conversion URL matching rules to the registered domains.

Note

Advertisers with an existing Insight Tag and LLA relationship must have their LLA account internally white listed.

Insight Tag Domains

Create an Insight Tag Domain

To begin, you must create an association between the website domain(s) and an advertiser account.

Each unique site needs to be registered to the advertiser account before using the Insight Tag. You can register multiple domain names to an Insight Tag.

POST https://api.linkedin.com/v2/insightTagDomains

Request Body Fields

Field Key Field Descriptions Example
account The sponsored account URN. Specified in the URL query parameter and the request JSON body. urn:li:sponsoredAccountUrn:123456
domainName The FQDN of the website that the partner intends to register. There should be no paths or protocols included. If multiple are provided, this behaves as a batch create. bigcompany.com

Schema

Response Field Key Response Field Descriptions
id The ID of the InsightTagDomain.
account The sponsored account URN.
domainName The exact domain name.
lastCallbackAt The last time the Insight Tag for this domain called back to the server. Expected to update no more than a couple of hours after the callback was received. In milliseconds.
created A timestamp corresponding to the creation of this resource. In milliseconds.
lastModified A timestamp corresponding to the last modification of this resource. If no modification has occurred since creation, lastModified should be the same as created. In milliseconds.

Sample Response

{
    "account": "urn:li:sponsoredAccount:123456",
    "created": 1447843020000,
    "domainName": "example.com",
    "id": 27858,
    "lastModified": 1450814011000
}

A successful response returns a 201 Created HTTP status code.

Batch Create

You can create multiple insightTagDomains by passing the X-RestLi-Method: BATCH_CREATE header and including multiple records in the elements array.

Sample Request

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:123456",
            "domainName": "example.com"
        },
        {
            "account": "urn:li:sponsoredAccount:123456",
            "domainName": "example2.com"
        }
    ]
}

Sample Response

The response to Batch Create will return an array with results for each record.

{
    "elements": [
        {
            "entity": {
                "account": "urn:li:sponsoredAccount:103319",
                "created": 1447843020000,
                "domainName": "example.com",
                "id": 27858,
                "lastModified": 1450814011000
            },
            "id": "27858",
            "status": 201
        },
        {
            "entity": {
                "account": "urn:li:sponsoredAccount:103319",
                "created": 1449693736000,
                "domainName": "example2.com",
                "id": 28128,
                "lastModified": 1449693736000
            },
            "id": "28128",
            "status": 201
        }
    ]
}

Get Insight Tag Domains

The following endpoint returns a single insightTagDomain record.

GET https://api.linkedin.com/v2/insightTagDomains/{insightTagDomainId}?account={sponsoredAccountUrn}

Sample Response

{ "created": 1447843020000, "domainName": "example.com", "lastModified": 1450814011000, "id": 27858, "account": "urn:li:sponsoredAccount:103319" }

Batch Get

Multiple records can be requested with a Batch Get that accepts multiple ids parameters each with an insightTagDomain ID.

GET https://api.linkedin.com/v2/insightTagDomains?ids={insightTagDomainId1}&ids={insightTagDomainId2}&ids={insightTagDomainId3}&account={sponsoredAccountUrn}

Sample Response

{
    "errors": {},
    "results": {
        "27858": {
            "account": "urn:li:sponsoredAccount:103319",
            "created": 1447843020000,
            "domainName": "example.com",
            "id": 27858,
            "lastCallbackAt": 1450814011000,
            "lastModified": 1450814011000
        },
        "28815": {
            "account": "urn:li:sponsoredAccount:103319",
            "created": 1456513904000,
            "domainName": "high.com",
            "id": 28815,
            "lastModified": 1456513904000
        }
    },
    "statuses": {}
}

Find Account's Insight Tag Domains

All Insight Tag Domains associated with an Ad Account can be used with the following endpoint:

GET https://api.linkedin.com/v2/insightTagDomains?q=account&account={sponsoredAccountURN}

For more precision, you can also include a domainName parameter.

GET https://api.linkedin.com/v2/insightTagDomains?q=accountAndDomainName&account={sponsoredAccountURN}&domainName={domainName}

Sample Response

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:12345",
            "created": 1447843020000,
            "domainName": "example.com",
            "id": 27858,
            "lastCallbackAt": 1450814011000,
            "lastModified": 1450814011000
        },
        {
            "account": "urn:li:sponsoredAccount:12345",
            "created": 1449693736000,
            "domainName": "example2.com",
            "id": 28128,
            "lastCallbackAt": 1450814011000,
            "lastModified": 1449693736000
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Insight Tags

Insight Tags associated with an advertiser should be placed in a common header or footer on an advertiser's site.

Get an Insight Tag

Insight Tags associated with a specified Ad Account can be fetched with the following endpoint.

GET https://api.linkedin.com/v2/insightTags?q=account&account={sponsoredAccountURN}

Sample Response

Returns tag with the HTML tag contents.

{
    "elements": [
        {
            "tag": "<script type=\"text/javascript\"></script>"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Insight Tag Permissions

There are two access roles for Insight Tag permissions: FULL (administrator) and USE_ONLY.

  • FULL has general administrative permissions to the Insight Tag.
  • USE_ONLY can only edit and view conversions and match rules.

More details about what actions each role can take are in the table below.

Access role Add/remove domains View Insight Tag Create conversions Update/ delete conversions View Insight Tag access Grant/revoke Insight Tag access
FULL Yes Yes Yes Yes Yes Yes
USE_ONLY Yes Yes Yes Yes Yes No

When creating an Insight Tag, the advertiser account creating the Insight Tag gets the FULL role by default. Alternatively, an advertiser account that does not have an Insight Tag can be granted FULL or USE_ONLY access to an Insight Tag from another advertiser account.

A Sponsored Account can have only one Insight Tag associated to it at any given time. An Insight Tag may have multiple ad accounts associated with it. An Insight Tag must have at least 1 account with FULL access assigned.

If a Sponsored Account with an existing Insight Tag wants to use a different or new Insight Tag, the account must:

  1. Ensure at least 1 other Ad Account has FULL access to the Insight Tag. This role must be passed to another Ad Account if no other Ad Account currently has FULL access.
  2. Revoke access to the Insight Tag for the original Ad Account.
  3. Give FULL access to a new Insight Tag that a different Ad Account currently has FULL access to.

Insight Tag Permissions for an Advertiser Account

To query for the access role associated to an advertiser account and insight tag, use q=account and the sponsoredAccountUrn.

GET https://api.linkedin.com/v2/insightTagsPermission?account={sponsoredAccountUrn}&q=account

Sample Response

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:511239630",
            "insightTag": "urn:tscp:insightTag:9617",
            "role": "FULL"
        },
        {
            "account": "urn:li:sponsoredAccount:511239630",
            "insightTag": "urn:tscp:insightTag:9876",
            "role": "FULL"
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Grant Insight Tag Access to a Different Advertiser Account

Give access to another Ad Account by granting an access role to an Insight Tag.

POST https://api.linkedin.com/v2/insightTagsPermission?action=grantAccess

Request Body Fields

Field key Field Descriptions
account The sponsored account URN.
insightTag The insight tag URN.
targetAccount The sponsored account URN of the recipient.
role FULL or USE_ONLY

Sample Request

{ "account": "urn:li:sponsoredAccount:123456", "insightTag": "urn:tscp:insightTag:9617", "targetAccount": "urn:li:sponsoredAccount:7890", "role": "FULL" }

Revoke Insight Tag Access from an Advertiser Account

Revoke access to another advertiser account by removing an access role to an Insight Tag.

An Insight Tag must be associated with at least one Ad Account. The API does not allow you to revoke access to an Insight Tag when there's only one remaining associated Ad Account because it would create an orphan Insight Tag.

POST https://api.linkedin.com/v2/insightTagsPermission?action=revokeAccess

Request Body Fields

Field key Field Descriptions
account The sponsored account URN.
insightTag The insight tag URN.
targetAccount The sponsored account URN of the recipient.

Sample Request

{
    "account": "urn:li:sponsoredAccount:123456",
    "insightTag": "urn:tscp:insightTag:9617",
    "targetAccount": "urn:li:sponsoredAccount:7890"
}

Conversions

LinkedIn conversion tracking is an analytical function powered by the LinkedIn Insight Tag. Conversions are actions a member makes that are valuable to your business. Conversion tracking gathers insights into post-click and view-through conversions of your LinkedIn ads campaigns, giving you the ability to measure the impact and ROI of your ads.

The Conversion API supports both event-specific and site-wide tags.

For more information on conversion tracking, see this help article.

Create a Conversion

Conversions can be created with the following endpoint. Include rules in the urlRules field to track site-wide conversions. Don't include any urlRules to track event-specific conversions.

POST https://api.linkedin.com/v2/conversions

Schema

Field Key Field Descriptions
domainId The insightTagDomain key that this Conversion resides under.
account The Sponsored Account URN that this Conversion resides under. This can be either specified in URL query parameter or in the request JSON body.
enabled Set to true or false to enable or disable this rule from matching on the advertiser’s website. The initial state can be either, but only rules that are enabled will trigger conversion events.
name A short name for this rule, which will be shown in the UI and in reports.
type The type of the rule. Can be one of the following:
  • ADD_TO_CART - The user added one or more things to their shopping cart.
  • DOWNLOAD - The user downloaded a file.
  • INSTALL - The user installed a plugin or an app.
  • KEY_PAGE_VIEW - The user viewed an important web page or app screen.
  • LEAD - The user filled out a lead generation form.
  • PURCHASE - The user made a purchase.
  • SIGN_UP - The user signed up for a web site or app service.
  • OTHER - Other case not listed above.
postClickAttributionWindowSize int, default="30" Specifies a user's settings on the post click attribution window in days. By setting these fields to something else, the advertiser can narrow the window. Allowed values are 1, 7, or 30.
viewThroughAttributionWindowSize int, default="7" Specifies a user's settings on the view through (post view) attribution window in days. By setting these fields to something else, the advertiser can narrow the window. Allowed values are 1, 7, or 30.
value Optional. The monetary value for this conversion. If this is set, the currency code should be identical to the currency set on the advertiser account.
currencyCode Identifying code for currency type. See currency codes for the valid codes.
amount The amount of money as a real number string.
campaigns Optional Deprecated. Use campaignConversions endpoint. An array that contains the Sponsored Campaigns associated with this Conversion. Campaigns should consist of the creative you want to show in order to drive a particular outcome on the advertiser’s website. The Sponsored Campaigns represent the media and the Conversion represents the outcome. If omitted, the Conversion will have an empty array of campaigns. If a conversion is not tied to any campaign, no conversions will are included in the report statistics.
urlRules An array that contains the Conversion URL match rules associated with this Conversion. There must be one or more present on creation.
type The type of this match rule that specifies how the URL will be matched. Can be one of the following:
  • EXACT - The match is exact.
  • STARTS_WITH - A prefix to match.
  • CONTAINS - A substring to match, multiple substrings can be supplied separated by an "OR" boolean.
matchValue The URL value text to match. Regular expressions or special syntax are not supported. Examples: 'www.example.com', 'example.com/download.php', 'example.com/download/coolWhitepaper'. For CONTAINS only: 'example.com/order OR example.com/checkout'. There is no need to include the protocol (for example, http, https).

Sample Request

{
    "account": "urn:li:sponsoredAccount:103319",
    "campaigns": [
        "urn:li:sponsoredCampaign:123",
        "urn:li:sponsoredCampaign:456"
    ],
    "domainId": 27858,
    "enabled": false,
    "name": "Seminar Purchase",
    "postClickAttributionWindowSize": 7,
    "type": "PURCHASE",
    "urlRules": [
        {
            "matchValue": "example.com/checkout",
            "type": "STARTS_WITH"
        }
    ],
    "value": {
        "amount": 1000.0,
        "currencyCode": "USD"
    },
    "viewThroughAttributionWindowSize": 30
}

Sample Response

{
    "account": "urn:li:sponsoredAccount:103319",
    "campaigns": [
        "urn:li:sponsoredCampaign:123",
        "urn:li:sponsoredCampaign:456"
    ],
    "created": 1456514258482,
    "domainId": 27858,
    "enabled": false,
    "id": 52579,
    "imagePixelTag": "<img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\" src=\"https://dc.ads.linkedin.com/collect/?pid=21987&conversionId=52579&fmt=gif\" />",
    "lastModified": 1456514258482,
    "name": "Seminar Purchase",
    "postClickAttributionWindowSize": 7,
    "type": "PURCHASE",
    "urlRules": [
        {
            "matchValue": "example.com/checkout",
            "type": "STARTS_WITH"
        }
    ],
    "value": {
        "amount": 1000.0,
        "currencyCode": "USD"
    },
    "viewThroughAttributionWindowSize": 7
}

A successful response returns a 201 Created HTTP status code and the ID in the X-LinkedIn-Id response header.

Batch Create

When you create multiple conversions, the header X-RestLi-Method must be included in the request and set to BATCH_CREATE.

Sample Request

{
    "elements": [
        {
            "account": "urn:li:sponsoredAccount:502381019",
            "campaigns": [
                "urn:li:sponsoredCampaign:124554663"
            ],
            "domainId": 28811,
            "enabled": false,
            "name": "Seminar Purchase",
            "type": "PURCHASE",
            "urlRules": [
                {
                    "matchValue": "example.com/checkout",
                    "type": "STARTS_WITH"
                }
            ],
            "value": {
                "amount": 1000.0,
                "currencyCode": "USD"
            }
        },
        {
            "account": "urn:li:sponsoredAccount:502381019",
            "campaigns": [
                "urn:li:sponsoredCampaign:124554663"
            ],
            "domainId": 28811,
            "enabled": false,
            "name": "Seminar Test",
            "type": "PURCHASE",
            "urlRules": [
                {
                    "matchValue": "example.com/checkin",
                    "type": "STARTS_WITH"
                }
            ],
            "value": {
                "amount": 1000.0,
                "currencyCode": "USD"
            }
        }
    ]
}

Get Conversions

Note

The field "lastCallbackAt" is a UNIX millisecond timestamp that represents the last time one or more of the URL match rules fired and called back to the server. It may not update in real-time.

The following endpoint returns a single conversion record.

GET https://api.linkedin.com/v2/conversions/{conversionId}?account={sponsoredAccountUrn}

Sample Response

{
  "account": "urn:li:sponsoredAccount:103319",
  "domainId": 27858,
  "name": "Seminar Signup",
  "created": 1449867352000,
  "lastModified": 1452035737000,
  "lastCallbackAt": 1449139800000,
  "urlRules": [
    {
      "matchValue": "example2.com/signup"
       "type": "EXACT"
    }
  ],
  "value": {
    "amount": 100.0,
    "currencyCode": "USD"
  },
  "campaigns": [
    "urn:li:sponsoredCampaign:1",
    "urn:li:sponsoredCampaign:8"
  ],
  "type": "SIGN_UP",
  "id": 49040,
  "enabled": false,
  "imagePixelTag": "<img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\" src=\"https://dc.ads.linkedin.com/collect/?pid=9597&conversionId=49040&fmt=gif\" />"
}

Batch Get

Multiple records can be requested with a Batch Get that accepts multiple ids parameters each with a conversion ID.

GET https://api.linkedin.com/v2/conversions?ids={conversionId1}&ids={conversionId2}&ids={conversionId3}&account={sponsoredAccountUrn}

Find Account's Conversions

All conversions associated with an ad account can be retrieved by using the following API which takes in a sponsoredAccount URN in the account parameter.

GET https://api.linkedin.com/v2/conversions?q=account&account={sponsoredAccountUrn}

For more precision, you can also include a sponsoredCampaign parameter to filter by a particular campaign.

GET https://api.linkedin.com/v2/conversions?q=campaign&account={sponsoredAccountUrn}&campaign={sponsoredCampaignUrn}

Sample Response

{
  "paging": {
    "count": 10,
    "start": 0,
    "links": []
  },
  "elements": [
    {
      "account": "urn:li:sponsoredAccount:123456",
      "domainId": 27858,
      "name": "example conv",
      "created": 1449139800000,
      "lastModified": 1449139800000,
      "lastCallbackAt": 1449139800000,
      "urlRules": [
        {
          "matchValue": "example.com/foo",
          "type": "EXACT"
        }
      ],
      "value": {
        "amount": 10.25,
        "currencyCode": "USD"
      },
      "campaigns": [
        "urn:li:sponsoredCampaign:1"
      ],
      "type": "PURCHASE",
      "id": 48561,
      "enabled": true,
      "imagePixelTag": "<img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\" src=\"https://dc.ads.linkedin.com/collect/?pid=9527&conversionId=48561&fmt=gif\" />",
    },
    {
      "account": "urn:li:sponsoredAccount:123456",
       "domainId": 27858,
       "name": "example conv number 2",
       "created": 1449150360000,
       "lastModified": 1449150360000,
       "urlRules": [
         {
           "matchValue": "example.com/foobar",
           "type": "EXACT"
         },
         {
            "matchValue": "example.com/foobarbaz",
            "type": "EXACT"
         }
       ],
       "campaigns": [
         "urn:li:sponsoredCampaign:1",
         "urn:li:sponsoredCampaign:2"
       ],
       "type": "DOWNLOAD",
       "id": 48570,
       "enabled": true,
       "imagePixelTag": "<img height=\"1\" width=\"1\" style=\"display:none;\" alt=\"\" src=\"https://dc.ads.linkedin.com/collect/?pid=9197&conversionId=48570&fmt=gif\" />"
    }
  ]
}

Update a Conversion

Use this to update your conversion. Only the field that changes needs to be specified. All fields can be modified, but should be done so with care. If you update campaigns or urlRules, then all the existing items in the array need to be specified. The update replaces the whole field, rather than appending the new updated values.

Updating a field does not change the data associated with previous conversion events. For example, changing the value of a conversion from $50 to $25 does not change the $50 value associated with conversion events for this rule that triggered previous to the change.

POST https://api.linkedin.com/v2/conversions/{conversionId}?account={sponsoredAccountUrn}

Sample Request

{
    "patch": {
        "$set": {
            "campaigns": [
                "urn:li:sponsoredCampaign:123"
            ],
            "enabled": false,
            "urlRules": [
                {
                    "matchValue": "www.linkedin.com/foo?q=1",
                    "type": "EXACT"
                },
                {
                    "matchValue": "www.linkedin.com/blah",
                    "type": "STARTS_WITH"
                }
            ]
        }
    }
}

Batch Partial Update

To make multiple updates in a single request, the header X-RestLi-Method must be included in the request and set to BATCH_PARTIAL_UPDATE.

POST https://api.linkedin.com/v2/conversions?account={sponsoredAccountUrn}&ids={conversionId1}&ids={conversionId2}
{
    "entities": {
        "3": {
            "patch": {
                "$set": {
                    "campaigns": [
                        "urn:li:sponsoredCampaign:123"
                    ],
                    "enabled": false,
                    "urlRules": [
                        {
                            "matchValue": "www.linkedin.com/foo?q=1",
                            "type": "EXACT"
                        },
                        {
                            "matchValue": "www.linkedin.com/blah",
                            "type": "STARTS_WITH"
                        }
                    ]
                }
            }
        },
        "4": {
            "patch": {
                "$set": {
                    "campaigns": [
                        "urn:li:sponsoredCampaign:123"
                    ],
                    "enabled": false,
                    "urlRules": [
                        {
                            "matchValue": "www.linkedin.com/foo?q=1",
                            "type": "EXACT"
                        },
                        {
                            "matchValue": "www.linkedin.com/blah",
                            "type": "STARTS_WITH"
                        }
                    ]
                }
            }
        }
    }
}

Sample Response

{
    "errors": {},
    "results": {
        "3": {
            "status": 204
        },
        "4": {
            "status": 204
        }
    }
}

Campaign Conversions

Campaign Conversions are association records between campaigns and conversions.

Create a Campaign Conversion

Sample Request

PUT https://api.linkedin.com/v2/campaignConversions/campaign=urn:li:sponsoredCampaign:337643194&conversion=urn:lla:llaPartnerConversion:70203
{
    "campaign": "urn:li:sponsoredCampaign:337643194",
    "conversion": "urn:lla:llaPartnerConversion:70203"
}

A successful response returns a 204 No Content HTTP status code.

Get Campaign Conversion

Sample Request

GET https://api.linkedin.com/v2/campaignConversions/campaign=urn:li:sponsoredCampaign:337643194&conversion=urn:lla:llaPartnerConversion:70203

Sample Response

{
    "associatedAt": 1506552037373,
    "campaign": "urn:li:sponsoredCampaign:337643194",
    "conversion": "urn:lla:llaPartnerConversion:70203"
}

A successful response returns a 200 OK HTTP status code.

Delete Campaign Conversion

Sample Request

DELETE https://api.linkedin.com/v2/campaignConversions/campaign=urn:li:sponsoredCampaign:337643194&conversion=urn:lla:llaPartnerConversion:70203

A successful response returns a 204 No Content HTTP status code.

Report Statistics

The Conversion Tracking Reporting API (adConversionReportStatistics) has been deprecated. The adAnalyticsV2 API has been enhanced to include conversion tracking data. See the FAQs on mapping adConversionReportStatistics to adAnalyticsV2.