Track a Conversion

Records a conversion event tied to a contact via their CampaignLark tracking ID.

Prerequisite: Conversion tracking must be enabled in workspace settings.

---

Endpoint

POST https://api.campaignlark.com/v1/conversions

---

Request Body

Field	Type	Required	Description
cl_track_id	string	required	The 24-character CampaignLark tracking ID from the email click.
type	string	required	Conversion type (e.g. "purchase", "signup"). Max 255 chars.
label	string	required	Human-readable label (e.g. "Order Completed"). Max 255 chars.
external_id	string	required	Your unique ID for this conversion (used for deduplication). Max 255 chars.
value	number	optional	Monetary value of the conversion. Required if currency is set.
currency	string	optional	ISO 4217 currency code (e.g. "USD", "EUR"). Required if value is set.
data	object	optional	Arbitrary key-value metadata attached to the conversion.

---

Sample Request

POST https://api.campaignlark.com/v1/conversions
Content-Type: application/json

{
  "cl_track_id": "6612a3f1c8b9e4d0a1234567",
  "type": "purchase",
  "label": "Order Completed",
  "external_id": "order-789",
  "value": 49.99,
  "currency": "USD",
  "data": {
    "product": "Widget Pro",
    "quantity": 2
  }
}

---

Success — 200 OK

{
  "data": {
    "queued": true
  }
}

---

Errors

Status	Message	Cause
400	Your workspace does not have conversion tracking enabled.	Conversion tracking is not enabled in workspace settings.
400	Please provide a valid CampaignLark tracking ID. It must be a 24 character string.	cl_track_id is missing, empty, or not exactly 24 characters.
400	Please provide a valid event type and label.	type or label is missing or empty.
400	Please provide a valid external ID.	external_id is missing or empty.
400	Please provide a valid currency. It is required for conversion tracking.	value was provided without currency.
400	Please provide a valid value. It is required for conversion tracking.	currency was provided without value.
400	We have already received this conversion. Please try with a different external ID.	A conversion with the same type and external_id already exists in the workspace.
400	It looks like the tracking ID you provided is invalid.	The cl_track_id does not match any known tracking record.
429	(billing message)	Event usage limit exceeded — workspace has exceeded its event usage quota for the billing period.

---

Data Constraints

The data field must be a flat JSON object. The following rules apply:

Constraint	Limit
Top-level type	Must be a JSON object (not an array or primitive).
Value types	Only string, number, boolean, or null are accepted. Nested objects and arrays are rejected.
String value length	1024 characters max per string value.
Keys per object	50 max.
Key length	128 characters max.
Forbidden key characters	Keys cannot be empty, start with $, or contain ..
Serialized size	8 KB max.

Requests that violate these rules are rejected with 400, for example:

• "data must be a flat object. The value for key X cannot be a nested object."
• "data must be a flat object. The value for key X cannot be an array."

---

Tracking ID

When conversion tracking is enabled for your workspace, CampaignLark automatically appends a cl_track_id query parameter to every link in your campaign emails. Each tracking ID is a unique 24-character string that identifies the specific contact and click.

For example, a link in your email such as:

https://yoursite.com/pricing

will be rewritten to:

https://yoursite.com/pricing?cl_track_id=6612a3f1c8b9e4d0a1234567

When a contact clicks through to your site, your system should capture the cl_track_id value from the URL query string and store it (e.g. in a cookie, session, or database). Later, when the contact completes a conversion — such as a purchase or signup — your system sends the stored cl_track_id back to CampaignLark via this endpoint so the conversion can be attributed to the correct contact and campaign.

---

Notes

• Each conversion must have a unique combination of type and external_id. If a conversion with the same type and external_id has already been recorded, the request will be rejected.
• value and currency must be sent together or both omitted.
• Each conversion counts towards your workspace's event usage quota. If your plan's event limit is reached, the API will return a 429 status until the next billing cycle.