Conversions API

  • Article

Try in Postman

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:

  1. Create a Conversion Rule
  2. Associate campaign(s) to the conversion rule
  3. Stream 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 (Each campaign): conversion actions are counted once for each campaign to which they can be attributed. (Default)
  • LAST_TOUCH_BY_CONVERSION (Single Campaign): conversion actions are counted once for each Conversion with at least one associated campaign. Learn more
    		•  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.
  • "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 / 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 / app service."
  • "OTHER" : Something that's not listed.
  • "TALENT_LEAD" : User submitted their information as a lead on LinkedIn Talent Media's Pipeline Builder Page.
  • "JOB_APPLY" : User clicked apply to a job on LinkedIn.
  • "SAVE": Saves a form or state in the flow.
  • "START_CHECKOUT": Begins the checkout process.
  • "SCHEDULE": Schedule a service or appointment.
  • "VIEW_CONTENT": The user viewed an section of the page or app screen(webview).
  • "VIEW_VIDEO": The user played a video.
  • "ADD_BILLING_INFO": The user added credit card or purchase details.
  • "BOOK_APPOINTMENT": The user reserved an appointment.
  • "REQUEST_QUOTE": The user requested a quote.
  • "SEARCH": The user searched within the app. Can also track using KEY_PAGE_VIEW that will fire from a search results page.
  • "SUBSCRIBE": The user subscribed to a service.
  • "AD_CLICK": The user clicked a 3rd party ad. (first party ads are tracked from LinkedIn)
  • "AD_VIEW": The user viewed an ad.
  • "COMPLETE_SIGNUP": The user completed registration process.
  • "SUBMIT_APPLICATION": The user submitted an application, same as COMPLETE_SIGNUP.
  • "PHONE_CALL": The user started a call, or performed phone-call specific event or submission.
  • "INVITE": The user sent/shared an invite.
  • "LOGIN": The user logged in to advertiser's service account.
  • "SHARE": The user shared content.
  • "DONATE": The user performed a donation
  • "ADD_TO_LIST": The user added a product to a wishlist.
  • "RATE": The user rated a service or a product.
  • "START_TRIAL": The user started a trial subscription. Overlaps with SUBSCRIBE.
  • "OUTBOUND_CLICK": The user left the app or page by clicking a link. (we won't capture the link).
  • "CONTACT": The user attempted to contact, by filling a form or a phone call.
    		•
    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 (Each campaign): conversion actions are counted once for each campaign to which they can be attributed. (Default)
  • LAST_TOUCH_BY_CONVERSION (Single Campaign): conversion actions are counted once for each Conversion with at least one associated campaign. Learn more
    		•  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.
  • "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 / 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 / app service."
  • "OTHER" : Something that's not listed.
  • "TALENT_LEAD" : User submitted their information as a lead on LinkedIn Talent Media's Pipeline Builder Page.
  • "JOB_APPLY" : User clicked apply to a job on LinkedIn.
  • "SAVE": Saves a form or state in the flow.
  • "START_CHECKOUT": Begins the checkout process.
  • "SCHEDULE": Schedule a service or appointment.
  • "VIEW_CONTENT": The user viewed an section of the page or app screen(webview).
  • "VIEW_VIDEO": The user played a video.
  • "ADD_BILLING_INFO": The user added credit card or purchase details.
  • "BOOK_APPOINTMENT": The user reserved an appointment.
  • "REQUEST_QUOTE": The user requested a quote.
  • "SEARCH": The user searched within the app. Can also track using KEY_PAGE_VIEW that will fire from a search results page.
  • "SUBSCRIBE": The user subscribed to a service.
  • "AD_CLICK": The user clicked a 3rd party ad. (first party ads are tracked from LinkedIn)
  • "AD_VIEW": The user viewed an ad.
  • "COMPLETE_SIGNUP": The user completed registration process.
  • "SUBMIT_APPLICATION": The user submitted an application, same as COMPLETE_SIGNUP.
  • "PHONE_CALL": The user started a call, or performed phone-call specific event or submission.
  • "INVITE": The user sent/shared an invite.
  • "LOGIN": The user logged in to advertiser's service account.
  • "SHARE": The user shared content.
  • "DONATE": The user performed a donation
  • "ADD_TO_LIST": The user added a product to a wishlist.
  • "RATE": The user rated a service or a product.
  • "START_TRIAL": The user started a trial subscription. Overlaps with SUBSCRIBE.
  • "OUTBOUND_CLICK": The user left the app or page by clicking a link. (we won't capture the link).
  • "CONTACT": The user attempted to contact, by filling a form or a phone call.
  • "MARKETING_QUALIFIED_LEAD": The user filled out a lead gen form, and has been filtered by advertiser to be marketing qualified lead.
  • "SALES_QUALIFIED_LEAD": The user filled out a lead gen form, and has been filtered by advertiser to be sales qualified lead.
    		•

    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 the id field in response body and in x-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 format urn:lla:llaPartnerConversion:ID where you need to replace ID with the conversion ID extracted when creating the conversion rule in this step by parsing id field from its response body or x-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:
  • SHA256_EMAIL,
  • LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID,
  • ACXIOM_ID,
  • ORACLE_MOAT_ID.
    		•
    userInfo (optional) userInfo Object containing additional fields for user matching. Currently supported fields are:
  • firstName,
  • lastName,
  • companyName,
  • title,
  • countryCode.
    		•
    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:
  • SHA256_EMAIL,
  • LINKEDIN_FIRST_PARTY_ADS_TRACKING_UUID,
  • ACXIOM_ID,
  • ORACLE_MOAT_ID.
    		•
    userInfo (optional) userInfo Object containing additional fields for user matching. Currently supported fields are:
  • firstName,
  • lastName,
  • companyName,
  • title,
  • countryCode.
    		•
    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 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 format urn: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
    • userInfo in the input request can be included for higher match rates and if included, it must provide both firstName and lastName.
    • If you are including userInfo without any valid idType in userIds, an empty list [] can be used for userIds.
    • 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.