Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Warning
Deprecation Notice: The Marketing Version 202502 (Marketing February 2025) has been sunset. We recommend that you migrate to the latest versioned APIs to avoid disruptions. For information on all the supported versions, refer to the migrations documentation. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
The LinkedIn Conversions API connects an advertiser’s server to LinkedIn, allowing measurement of LinkedIn marketing campaign performance regardless of where the conversion occurs. This data is used to optimize campaigns and improve attribution, data reliability, and delivery. For more information, refer to LinkedIn Conversions API.
Permissions
| Permission | Description |
|---|---|
rw_conversions |
Upload your conversion data to LinkedIn and manage your conversion tracking. |
r_ads |
Read access to an authenticated member's ad accounts. |
The following conditions must be met for a successful call:
- Scope permissions to
rw_conversions,r_ads. - The user assigning permission holds one of the following roles
in the ad account:
ACCOUNT_BILLING_ADMINACCOUNT_MANAGERCAMPAIGN_MANAGERCREATIVE_MANAGER
For more information on ad account roles and permissions, refer to the following:
Scope permissions for 3-legged OAuth
rw_conversions(Read/Write).r_ads(Read)
Requirements
Following are the requirements to send conversion events:
Schema
For more information on the schema, refer to Conversion API Schema.
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 a conversion name, ad account URN, conversion method, and type (key conversion behavior).
Note
X-Restli-Protocol-Version: 2.0.0must 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.
Sample Request
POST https://api.linkedin.com/rest/conversions?autoAssociationType=ALL_CAMPAIGNS
{
"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 CreatedHTTP status code is returned if the request is successful and conversion rule ID is in theidfield in response body and inx-restli-idresponse header. - A
400 Bad Requestis returned if the request doesn't 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 using the endpoint that takes a sponsoredAccount URN in the account parameter. Parse the response to filter for Conversions API rules where conversionMethod is set to CONVERSIONS_API and enabled is set to 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"
}
]
}
Note
For more information on other HTTP methods such as GET, BATCH GET, and UPDATE, refer to Conversion Tracking.
Associate Campaigns to Conversion Rule
When creating a new conversion rule with the POST /conversions endpoint, if you did not include the query parameter autoAssociationType, then you must associate conversion rule with specific campaigns using the Campaign Conversions API as mentioned. Otherwise, you can skip this step and proceed to Streaming conversion Events.
Campaign Conversions API can be used to associate specific 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 the LinkedIn Campaign Manager tool (Go to Ad Account > Measurement > Conversion tracking, and select the conversion rule created in previous step where Data source should list the selected partner integration or Direct API, click Next step and in Step 3 Review, 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.
PartnerConversionURNis of the formaturn:lla:llaPartnerConversion:IDwhere you need to replace ID with the conversion ID extracted when creating the conversion rule in this step by parsingidfield from its response body orx-restli-idresponse header .- It is important to associate each conversion with an active campaign, as conversions can only be attributed to campaigns they are associated with. Associate your conversions with as many applicable campaigns as possible to maximize attribution and visibility.
PUT https://api.linkedin.com/rest/campaignConversions/(campaign:{sponsoredCampaignURN},conversion:{conversionURN})
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 method that accepts ids parameter with a list of campaign URN and conversion URN. The campaign and conversion URNs should be passed in a list format and URL encoded as shown in the following examples. Be sure to include request header 'X-RestLi-Method: BATCH_UPDATE' to indicate batch update.
PUT https://api.linkedin.com/rest/campaignConversions?ids=List((campaign:{sponsoredCampaignURN},conversion:{conversionURN}))
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 are used for matching with LinkedIn.
Note
Explore the Payload Builder to create the conversion events payload based on your inputs. For more information, refer to the payload builder documentation.
POST https://api.linkedin.com/rest/conversionEvents
Schema
For more information on the schema, refer to Streaming Conversion Events Schema.
Adding Single Conversion Event
This endpoint allows you to stream a single conversion event, including 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 prevent failures, ensure that your request meets all the validation requirements.
Adding Multiple Conversion Events in a Batch
To stream multiple conversions in a batch, include the X-RestLi-Method header set to BATCH_CREATE. You can send up to 5,000 conversion events in a single batch request. If you encounter issues, try using a smaller batch size. This method helps avoid rate limit throttling when sending large numbers of conversion events.
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's any invalid value in the request body like missing required field or invalid data type, all records 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
600requests per minute from your member access token and a maximum of300,000requests per day from your member access token, otherwise your requests can get throttled due to rate limits. - Use batch requests for sending up to
5,000conversion events in a single batch request to avoid getting throttled from 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 the 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 shouldn't be empty string}] | The required field is missing. |
| 400 | Invalid Conversion information provided, this event(s) is associated to a conversion that's marked as deleted. Conversion enabled should be true | Please make sure the conversion rule enabled is set as true; otherwise conversion events can't be streamed to a deleted conversion rule. |
| 400 | 365 is not an available post-click window selection. Available: [1, 7, 28, 30, 90] | 365 days is a supported value for these conversion types:
|
| 422 | Index: 0, ERROR :: /conversionHappenedAt :: field is required but not found and has no default value\n | The required field is missing. |