LinkedIn Conversions

This guide covers how to submit conversions to LinkedIn Ads through the TNT Growth API.

Authentication

All requests require an x-api-key header with your client-specific API key provided by TNT Growth.

-H "x-api-key: YOUR_API_KEY"

Submitting a Conversion

Endpoint

POST /api/linkedin/events/add

Request Body Schema

Field	Type	Required	Description
accountId	string	Yes	Your LinkedIn Ad Account ID (provided during onboarding)
conversionId	string	Yes	LinkedIn Conversion ID from the conversion rule
conversionTime	number	Yes	Unix timestamp (seconds) of when the conversion occurred
userData	object	No	Customer identifiers for matching (see below)
userInfo	object	No	Additional user info — { firstName, lastName }
metadata	object	No	Conversion goal metadata (see below)
ingestionSource	string	No	Origin of the event (e.g. pixel, conversion-api)
utmSource	string	No	UTM source parameter (e.g. linkedin) — stored for attribution reporting
utmMedium	string	No	UTM medium parameter (e.g. cpc) — stored for attribution reporting
utmCampaign	string	No	UTM campaign name — stored for attribution reporting
utmTerm	string	No	UTM search keyword — stored for attribution reporting
utmContent	string	No	UTM content parameter (ad/creative variant) — stored for attribution reporting

User Data Fields (userData)

Include as many identifiers as possible to improve match quality.

Field	Type	Description
email	string	Customer email address
phone	string	Customer phone number
liFatId	string	LinkedIn First-Party Ad Tracking ID captured from the ad click
companyName	string	Customer company name

Metadata Fields (metadata)

Field	Type	Description
customConversionGoalId	string	LinkedIn custom conversion goal ID
customConversionGoalName	string	LinkedIn custom conversion goal name

Example Request

curl -X POST https://flex.tntgrowth.io/api/linkedin/events/add \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "accountId": "510876543",
    "conversionId": "12345678",
    "conversionTime": 1778043599,
    "userData": {
      "email": "customer@example.com",
      "phone": "+15551234567",
      "liFatId": "AbCdEfGhIjKlMnOp"
    },
    "userInfo": {
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "utmSource": "linkedin",
    "utmMedium": "paid-social",
    "utmCampaign": "demand-gen-q2",
    "utmTerm": "treatment programs",
    "utmContent": "sponsored-content-variant-b"
  }'

Example Response

{
  "message": "Conversion successfully queued for LinkedIn! 510876543",
  "data": {
    "submissionId": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c",
    "duplicate": false
  }
}

When a conversion is dedup-skipped (the same event was submitted within the last 24 hours), submissionId is null and duplicate is true.

Checking Submission Status

After submitting a conversion, use the submission ID to check processing status.

Endpoint

GET /api/conversions/submissions/:submissionId

Example Request

curl https://flex.tntgrowth.io/api/conversions/submissions/8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "id": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c",
  "source": "LINKEDIN",
  "externalAccountId": "510876543",
  "expectedCount": 1,
  "createdAt": "2026-05-11T12:00:00.000Z",
  "scheduledFor": null,
  "counts": {
    "success": 1,
    "failed": 0
  },
  "status": "complete"
}

Status Values

Status	Description
pending	Conversion is queued and waiting to be processed
pending_delivery	Submission is scheduled for future delivery. Currently only emitted by Google Ads ingest paths; LinkedIn submissions never enter this state.
complete	Conversion processed successfully
complete_with_errors	Processing finished but some conversions failed — use GET /api/conversions/linkedin/failed?submissionId=<id> to fetch the actual error messages
stalled	Processing has not progressed — contact support

The scheduledFor field is always null for LinkedIn submissions and is included only for schema parity with Google Ads, which uses it for deferred delivery.

Inspecting Failed Conversions In Your Batch

When a submission ends with complete_with_errors, the submission status endpoint surfaces only the count of failed rows. Fetch the actual error messages with:

GET /api/conversions/linkedin/failed?submissionId=<submissionId>

The response payload mirrors the Google Ads failed-conversion shape — see Google Ads → Inspecting Failed Conversions In Your Batch.

Best Practices

• Include liFatId when available — LinkedIn's first-party tracking ID provides the strongest attribution signal
• Send userData with email and/or phone to improve match rates for offline events
• Use accurate timestamps — conversionTime should reflect when the conversion actually occurred
• Match conversionId to the correct conversion rule in your LinkedIn Campaign Manager
• Poll with a delay — wait 30-60 seconds after submission before checking status