Conversions API
LinkedIn Conversions API creates a direct connection between marketing data from an advertiser’s server and LinkedIn. This enables advertisers to measure the performance of their LinkedIn marketing campaigns no matter where the conversion happens and use this data to power campaign optimization. Conversions API can help strengthen performance and decrease cost per action with more complete attribution, improved data reliability, and better optimized delivery. Refer to LinkedIn Conversions API for more information.
Permissions
Permission | Description |
---|---|
rw_conversions |
Upload your conversion data to LinkedIn and manage your conversion tracking data. |
r_ads |
Read access to an authenticated member's ad accounts. |
There are two conditions for successful calls: (1) Scope permissions to rw_conversions
, r_ads
and (2) the user assigning permission holding one of the following roles in the Ad Account.
Scope permissions for 3-legged Oauth
rw_conversions
(Read/Write)r_ads
(Read)
Ad Account Roles:
ACCOUNT_BILLING_ADMIN
ACCOUNT_MANAGER
CAMPAIGN_MANAGER
CREATIVE_MANAGER
For more information on Ad Account roles and permissions:
Requirements
See the following requirements for sending conversion events:
Note
X-Restli-Protocol-Version: 2.0.0
must be passed as a request header in all your API requests.LinkedIn-Version: {yyyymm}
must be passed as a request header in all your API requests as per Versioning.
Schema
Field Name | Type | Description | Example |
---|---|---|---|
account | URN | The Sponsored Ad Account URN that this Conversion will be created under. This can be either specified in query parameter or in the request body. Refer Find Ad Accounts By Authenticated User API to select ad account. | urn:li:sponsoredAccount:12345 |
name | string | A short name for this rule, which will be shown in the UI and in reports. | Summer_Sale CRM Leads |
conversionMethod | string | A method enum that specifies how a conversion event should be registered. For streaming conversions via API, the only supported value here is CONVERSIONS_API . |
CONVERSIONS_API |
enabled (optional) | boolean (default= true) | Set to true or false to enable or disable this rule from matching conversions. The initial state can be either, but only rules that are enabled will trigger conversion events. Default is true. | true |
postClickAttributionWindowSize (optional) | int (default= 30) | Conversion window timeframe (in days) of a member clicking on a LinkedIn Ad (a post-click conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 30. Learn more | 90 |
viewThroughAttributionWindowSize (optional) | int (default= 7) | Conversion window timeframe (in days) of a member seeing a LinkedIn Ad (a view-through conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 7. Learn more | 30 |
attributionType (optional) | string (default= LAST_TOUCH_BY_CAMPAIGN ) |
The model that describes how conversion actions are to be counted. Acceptable values are: LAST_TOUCH_BY_CAMPAIGN and LAST_TOUCH_BY_CONVERSION |
LAST_TOUCH_BY_CAMPAIGN |
type | string | Type of the conversion to track for this conversion rule. Eg. PURCHASE, LEAD, SIGNUP etc. Complete list can be found below. |
Field Name | Type | Description | Example |
---|---|---|---|
account | URN | The Sponsored Ad Account URN that this Conversion will be created under. This can be either specified in query parameter or in the request body. Refer Find Ad Accounts By Authenticated User API to select ad account. | urn:li:sponsoredAccount:12345 |
name | string | A short name for this rule, which will be shown in the UI and in reports. | Summer_Sale CRM Leads |
conversionMethod | string | A method enum that specifies how a conversion event should be registered. For streaming conversions via API, the only supported value here is CONVERSIONS_API . |
CONVERSIONS_API |
enabled (optional) | boolean (default= true) | Set to true or false to enable or disable this rule from matching conversions. The initial state can be either, but only rules that are enabled will trigger conversion events. Default is true. | true |
postClickAttributionWindowSize (optional) | int (default= 30) | Conversion window timeframe (in days) of a member clicking on a LinkedIn Ad (a post-click conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 30. Learn more | 90 |
viewThroughAttributionWindowSize (optional) | int (default= 7) | Conversion window timeframe (in days) of a member seeing a LinkedIn Ad (a view-through conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 7. Learn more | 30 |
attributionType (optional) | string (default= LAST_TOUCH_BY_CAMPAIGN ) |
The model that describes how conversion actions are to be counted. Acceptable values are: LAST_TOUCH_BY_CAMPAIGN and LAST_TOUCH_BY_CONVERSION |
LAST_TOUCH_BY_CAMPAIGN |
type | string | Type of the conversion to track for this conversion rule. Eg. PURCHASE, LEAD, SIGNUP etc. Complete list can be found below. |
Field Name | Type | Description | Example |
---|---|---|---|
account | URN | The Sponsored Ad Account URN that this Conversion will be created under. This can be either specified in query parameter or in the request body. Refer Find Ad Accounts By Authenticated User API to select ad account. | urn:li:sponsoredAccount:12345 |
name | string | A short name for this rule, which will be shown in the UI and in reports. | Summer_Sale CRM Leads |
conversionMethod | string | A method enum that specifies how a conversion event should be registered. For streaming conversions via API, the only supported value here is CONVERSIONS_API . |
CONVERSIONS_API |
enabled (optional) | boolean (default= true) | Set to true or false to enable or disable this rule from matching conversions. The initial state can be either, but only rules that are enabled will trigger conversion events. Default is true. | true |
postClickAttributionWindowSize (optional) | int (default= 30) | Conversion window timeframe (in days) of a member clicking on a LinkedIn Ad (a post-click conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 30. Learn more | 90 |
viewThroughAttributionWindowSize (optional) | int (default= 7) | Conversion window timeframe (in days) of a member seeing a LinkedIn Ad (a view-through conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 7. Learn more | 30 |
attributionType (optional) | string (default= LAST_TOUCH_BY_CAMPAIGN ) |
The model that describes how conversion actions are to be counted. Acceptable values are: LAST_TOUCH_BY_CAMPAIGN and LAST_TOUCH_BY_CONVERSION |
LAST_TOUCH_BY_CAMPAIGN |
type | string | Type of the conversion to track for this conversion rule. Eg. PURCHASE, LEAD, SIGNUP etc. Complete list can be found below. qualifiedLeads metric shows the total count of qualified leads attributed to the entities in the given time range and costPerQualifiedLead returns the number of qualified leads divided by ad spend.) |
Field Name | Type | Description | Example |
---|---|---|---|
account | URN | The Sponsored Ad Account URN that this Conversion will be created under. This can be either specified in query parameter or in the request body. Refer Find Ad Accounts By Authenticated User API to select ad account. | urn:li:sponsoredAccount:12345 |
name | string | A short name for this rule, which will be shown in the UI and in reports. | Summer_Sale CRM Leads |
conversionMethod | string | A method enum that specifies how a conversion event should be registered. For streaming conversions via API, the only supported value here is CONVERSIONS_API . |
CONVERSIONS_API |
enabled (optional) | boolean (default= true) | Set to true or false to enable or disable this rule from matching conversions. The initial state can be either, but only rules that are enabled will trigger conversion events. Default is true. | true |
postClickAttributionWindowSize (optional) | int (default= 30) | Conversion window timeframe (in days) of a member clicking on a LinkedIn Ad (a post-click conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 30. Learn more | 90 |
viewThroughAttributionWindowSize (optional) | int (default= 7) | Conversion window timeframe (in days) of a member seeing a LinkedIn Ad (a view-through conversion) within which conversions will be attributed to a LinkedIn ad. Allowed values are 1, 7, 30 or 90. Default is 7. Learn more | 30 |
attributionType (optional) | string (default= LAST_TOUCH_BY_CAMPAIGN ) |
The model that describes how conversion actions are to be counted. Acceptable values are: LAST_TOUCH_BY_CAMPAIGN and LAST_TOUCH_BY_CONVERSION |
LAST_TOUCH_BY_CAMPAIGN |
type | string | Type of the conversion to track for this conversion rule. Eg. PURCHASE, LEAD, SIGNUP etc. Complete list can be found below. qualifiedLeads metric shows the total count of qualified leads attributed to the entities in the given time range and costPerQualifiedLead returns the number of qualified leads divided by ad spend.) |
Create a Conversion Rule
Create one or more conversion rules with the /conversions endpoint for each conversion type that you want to track and set conversionMethod
to CONVERSIONS_API
for streaming conversion events through API. Each conversion rule should include conversion name, ad account URN, conversion method, type (key conversion behavior).
Sample Request
POST https://api.linkedin.com/rest/conversions
{
"name": "Conversion API Segment 1",
"account": "urn:li:sponsoredAccount:5123456",
"conversionMethod": "CONVERSIONS_API",
"postClickAttributionWindowSize": 30,
"viewThroughAttributionWindowSize": 7,
"attributionType": "LAST_TOUCH_BY_CAMPAIGN",
"type": "LEAD"
}
Sample Response
- A
201 Created
HTTP status code is returned if the request is successful and conversion rule ID is in theid
field in response body and inx-restli-id
response header. - A
400 Bad Request
is returned if the request does not pass the validation check. Please check the error message to understand what validation failed.
Find Conversion Rules by Ad Account
All conversion rules associated with an ad account can be retrieved by using the following endpoint which takes in a sponsoredAccount
URN in the account
parameter, and then parsing the response to filter conversions where conversionMethod
is set to CONVERSIONS_API
and enabled
is true
.
Sample Request
GET https://api.linkedin.com/rest/conversions?q=account&account=urn%3Ali%3AsponsoredAccount%3A{sponsoredAccountId}
Sample Response
{
"elements": [
{
"postClickAttributionWindowSize": 30,
"viewThroughAttributionWindowSize": 7,
"created": 1563230311551,
"type": "LEAD",
"enabled": true,
"name": "Conversion API Segment 2",
"lastModified": 1563230311551,
"id": 104012,
"attributionType": "LAST_TOUCH_BY_CAMPAIGN",
"conversionMethod": "CONVERSIONS_API",
"account": "urn:li:sponsoredAccount:51234560"
},
{
"postClickAttributionWindowSize": 30,
"viewThroughAttributionWindowSize": 7,
"created": 1563230255308,
"type": "PURCHASE",
"enabled": true,
"name": "Conversion API Segment 3",
"lastModified": 1563230265652,
"id": 104004,
"attributionType": "LAST_TOUCH_BY_CAMPAIGN",
"conversionMethod": "CONVERSIONS_API",
"account": "urn:li:sponsoredAccount:51234560"
}
]
}
For more information on other http methods like GET, BATCH GET, UPDATE etc., see Conversion Tracking
Associate Campaigns to Conversion Rule
Campaign Conversions API is used to associate campaigns to a Conversion Rule ID. Only the campaigns associated with the conversion rule are eligible for attributing tracked Conversions for reporting.
Advertisers can also associate campaigns to conversion directly from Campaign Manager (Go to Ad Account > Analyze > Conversion Tracking, and look for conversion rule created in previous step where Data source should list the selected partner integration (or Direct API) , click Next step and select all campaigns to track conversions) or Add conversions to existing advertising campaigns.
Note
- Refer Search for Campaigns API to get list of active sponsored campaign URNs and then pass them to this endpoint.
PartnerConversionURN
is of the formaturn:lla:llaPartnerConversion:ID
where you need to replace ID with the conversion ID extracted when creating the conversion rule in this step by parsingid
field from its response body orx-restli-id
response header .- Make sure to include
X-Restli-Protocol-Version: 2.0.0
in the request header. - It is important to associate each conversion with an active campaign/s as we can only attribute conversions to a campaign if the conversion/s are associated to that campaign. Associate your conversions to as many applicable campaigns as possible in order to maximize attribution and visibility.
Sample Request
PUT https://api.linkedin.com/rest/campaignConversions/(campaign:urn%3Ali%3AsponsoredCampaign%3A337643194,conversion:urn%3Alla%3AllaPartnerConversion%3A70203)
{
"campaign": "urn:li:sponsoredCampaign:337643194",
"conversion": "urn:lla:llaPartnerConversion:70203"
}
Sample Response
A successful response returns a 204 No Content
HTTP status code.
Batch Associate Multiple Campaigns to Conversion Rule
Multiple campaign conversions can be created with a Batch Update that accepts IDs parameter each with a campaign URN and conversion URN. The campaign and conversion URNs should be passed in a List format and encoded as shown in the examples below.
Sample Request
PUT https://api.linkedin.com/rest/campaignConversions?ids=List((campaign:urn%3Ali%3AsponsoredCampaign%3A345396555,conversion:urn%3Alla%3AllaPartnerConversion%3A104004),(campaign:urn%3Ali%3AsponsoredCampaign%3A345396777,conversion:urn%3Alla%3AllaPartnerConversion%3A104004))
{
"entities":
{
"(campaign:urn%3Ali%3AsponsoredCampaign%3A345396555,conversion:urn%3Alla%3AllaPartnerConversion%3A104004)":{
"campaign":"urn:li:sponsoredCampaign:345396555",
"conversion":"urn:lla:llaPartnerConversion:104004"
},
"(campaign:urn%3Ali%3AsponsoredCampaign%3A345396777,conversion:urn%3Alla%3AllaPartnerConversion%3A104004)":{
"campaign":"urn:li:sponsoredCampaign:345396777",
"conversion":"urn:lla:llaPartnerConversion:104004"
}
}
}
Streaming Conversion Events
Stream conversion events from your server to LinkedIn on the conversion rule previously created, using the /conversionEvents endpoint. Each event should be accompanied by one or more user identifiers that will be used for matching with LinkedIn.
POST https://api.linkedin.com/rest/conversionEvents
Schema
Field | Type | Description | Example |
---|---|---|---|
conversion | URN | URN of the conversion rule created through API. | urn:lla:llaPartnerConversion:123 |
conversionHappenedAt | long | Epoch timestamp in milliseconds at which the conversion event happened. Note: If your source records conversion timestamp in seconds, please insert 000 at the end to transform it to milliseconds. | 1590739275000 |
conversionValue (optional) | Object | The monetary value for this conversion. It contains “currencyCode” in ISO format (e.g. “USD”) and the “amount” value of the conversion in decimal string. (e.g. “100.05”). Advertisers can set conversion values dynamically here or set a fix value when creating conversion. | {"currencyCode": "USD", "amount": "50.0"} |
eventId (optional) | string | The unique id generated by advertisers to indicate each event. This field is optional and is used for deduplication. | ABCDppSv6KBwg |
user | ConversionEventUser | Object containing userIds and userInfo attributes of the user who performed the conversion. |
See Sample Request below. |
ConversionEventUser
The user attributes related to the user who performed the conversion event.
Field | Type | Description |
---|---|---|
userIds | List (idType,idValue) | List of one or more identifiers to match the conversion user with objects containing "idType" and "idValue". Currently supported idType are: |
userInfo (optional) | userInfo | Object containing additional fields for user matching. Currently supported fields are: |
Field | Type | Description |
---|---|---|
userIds | List (idType,idValue) | List of one or more identifiers to match the conversion user with objects containing "idType" and "idValue". Currently supported idType are: |
userInfo (optional) | userInfo | Object containing additional fields for user matching. Currently supported fields are: |
lead (optional) | LeadGenFormResponseUrn | The leadGenFormResponse is generated when users submit Linkedin Lead-gen form and advertisers can download it from Campaign Manager UI or Lead Sync API. It is in format of urn:li:leadGenFormResponse:id |
idType
Field | Type | Description |
---|---|---|
SHA256_EMAIL | string | Email address of the contact associated with the conversion event which needs to be converted to lower case and then hashed in SHA256 format, a HEX encoded string with a maximum length of 64 characters. |
LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID | string | First party cookie or Click Id. Advertisers need to enable enhanced conversion tracking from Campaign Manager in order to activate first party cookies that appends a click ID parameter li_fat_id to the click URLs. Refer Enabling Click Ids for implementation details. |
ACXIOM_ID | string | User identifier for matching with LiveRamp identity graph. |
ORACLE_MOAT_ID | string | User identifier for matching with Oracle MOAT Identity. |
userInfo
Field | Type | Description | Example |
---|---|---|---|
firstName | string | The first name of the contact to match the conversion. | Mike |
lastName | string | The last name of the contact to match the conversion. | Smith |
companyName (optional) | string | A plain text string representing the company of the contact to match. | Microsoft |
title (optional) | string | A plain text string representing the title name of the contact to match. | Software Engineer |
countryCode (optional) | string | An ISO standardized two letter country code representing the country of the contact to match. | US |
Input Data Validation
An input request will be validated and it will fail if the following validation rules are not met:
conversion
must be a valid URN with formaturn:lla:llaPartnerConversion:<id>
- The authenticated user must have a valid user access role (other than VIEWER role) on the ad account where the conversion rule is created.
userIds
in the input request must provide at least one of the following:- A valid userId with idType
SHA256_EMAIL
Or - A valid userId with idType
LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID
Or - A valid userId with idType
ACXIOM_ID
Or - A valid userId with idType
ORACLE_MOAT_ID
- A valid userId with idType
userInfo
in the input request can be included for higher match rates and if included, it must provide bothfirstName
andlastName
.- If you are including
userInfo
without any valididType
inuserIds
, an empty list [] can be used foruserIds
. conversionHappenedAt
must be a valid timestamp which is number of milliseconds since epoch time, and timestamp should be within the past 90 days.
Adding Single Conversion Event
This endpoint allows you to stream a single conversion event which can include different match identifiers for the same user.
Sample Request
POST https://api.linkedin.com/rest/conversionEvents
{
"conversion": "urn:lla:llaPartnerConversion:123",
"conversionHappenedAt": 1590739275000,
"conversionValue": {
"currencyCode": "USD",
"amount": "50.0"
},
"user": {
"userIds": [ {
"idType": "SHA256_EMAIL",
"idValue": "bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc41f1"
}, {
"idType": "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
"idValue": "df5gf5-gh6t7-ph4j7h-fgf6n1"
} ],
"userInfo": {
"firstName": "mike",
"lastName": "smith",
"title": "software engineer",
"companyName": "microsoft",
"countryCode": "US"
}
},
"eventId" : "abc12345"
}
Sample Response
A successful response returns a 201 Created
HTTP status code.
A failed response returns a 400 Bad Request
status code. To avoid failures, make sure you verify the validation process.
Adding Multiple Conversion Events in a Batch
If you would like to stream multiple conversions in a batch, the header X-RestLi-Method
must be included in the request and set to BATCH_CREATE
. You may stream up to 5000 conversion events in a single batch request. If you see issues with your batch request responses, you may try to resubmit with smaller batch size.
Sample Request
POST https://api.linkedin.com/rest/conversionEvents
'X-RestLi-Method': 'BATCH_CREATE'
{
"elements":
[
{
"conversion": "urn:lla:llaPartnerConversion:123",
"conversionHappenedAt": 1590739275000,
"conversionValue": {
"currencyCode": "USD",
"amount": "50.0"
},
"user": {
"userIds": [ {
"idType": "SHA256_EMAIL",
"idValue": "bad8677b6c86f5d308ee82786c183482a5995f066694246c58c4df37b0cc41f1"
}
],
"userInfo": {
"firstName": "mike",
"lastName": "smith",
"title": "software engineer",
"companyName": "microsoft",
"countryCode": "US"
}
},
"eventId" : "abc234"
}, {
"conversion": "urn:lla:llaPartnerConversion:123",
"conversionHappenedAt": 162723579000,
"conversionValue": {
"currencyCode": "USD",
"amount": "100.0"
},
"user": {
"userIds": [ {
"idType": "SHA256_EMAIL",
"idValue": "dsfgrtg56u767ujy982fgnbmcsdocl46c58c56b650cik230bb9"
}, {
"idType": "LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID",
"idValue": "ufh8h5-gh6t7-ph4j7h-mkl86n1"
}],
"userInfo": {
"firstName": "jason",
"lastName": "bourne",
"title": "tech lead",
"companyName": "github",
"countryCode": "US"
}
},
"eventId" : "abc345"
}
]
}
Sample Response
A successful response returns a 201 Created
HTTP status code.
400 Bad Request is returned if the request is incorrect. The error message contains a reference to batchIndex
, with the index of the array element in the request payload that caused the error.
If there is any invalid value in the request body like missing required field or invalid hash value in email, all records will fail and you’ll need to resubmit the entire payload after correcting the data as indicated in the response body message.
Note
- Send a maximum of 300 requests per minute from your app otherwise your requests may get throttled due to rate limits.
- Send multiple user identifiers if available, to increase match rates. This is important, as only matched events can be used for attribution and optimization.
API Error Details
HTTP Status Code | ERROR MESSAGE | DESCRIPTION |
---|---|---|
400 | BAD_REQUEST | Request has a syntax error or validation error. Please check the error message to understand what part of request failed and resubmit with valid data. |
401 | EMPTY_ACCESS_TOKEN | Empty oauth2 access token. |
403 | USER_NOT_AUTHORIZED | User should have access to the ad account provided in the request and/or the required permissions. |
400 | Validation failed because [{field=Invalid Conversion time, batchIndex=0, type=INVALID_CONVERSION_TIME_FIELD_VALUE, message=Conversion time should be within 90 days.}] | Please make sure conversion timestamp in milliseconds is from past 90 days. |
400 | Validation failed because [{field=Multiple fields issue, batchIndex=0, type=INVALID_USER_IDENTIFICATION_FIELD_VALUE, message=The request must contain one of these fields: SHA256_EMAIL or LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID or ACXIOM_ID or ORACLE_MOAT_ID or (firstName and lastName),and the input should not be empty string}] | Missing required field |
422 | Index: 0, ERROR :: /conversionHappenedAt :: field is required but not found and has no default value\n | Missing required field |