Conversion Tracking API (Hybrid Style)

Overview

The Crazy Egg Conversion Tracking API lets you record goal conversions directly from your own systems — for example, when a user completes a purchase, signs up, or submits a form — even if the action happens outside the Crazy Egg tracking script.

You can use this API to:

Include monetary values, UTM parameters, and custom fields

Track conversions from servers, CRMs, or apps

Associate conversions with a specific user identifier

API Endpoint

All requests go to:

https://track.crazyegg.com/api/v1

Authentication

1. Enable the API for your site inside your Crazy Egg Dashboard.
2. Generate a Site API Key.
3. Include it in every request using the following HTTP header:
   

Authorization: key YOUR_API_KEY

Example

Authorization: key 2YolaLxq2Uucziitirao4DijtluVtSEnDiFKyL5PY8A

⚠️ The example key above is for illustration only — it will not work.

Sending Conversion Events

Send HTTP POST requests with a JSON body to the API endpoint.

Example using cURL:

curl \
  --data-binary '{
    "goalConversions": [
      {
        "goalName": "my goal",
        "userIdentifier": "user@example.com"
      }
    ]
  }' \
  --header 'Authorization: key 2YolaLxq2Uucziitirao4DijtluVtSEnDiFKyL5PY8A' \
  https://track.crazyegg.com/api/v1

You can include 1–25 conversions in a single request.
Each conversion object supports multiple optional properties listed below.

Goal Conversion Object Reference

Each event is sent inside an array called goalConversions.

{
  "goalConversions": [
    {
      "goalName": "added item to cart",
      "userIdentifier": "uid-54321",
      "url": "https://example.com/about",
      "value": 1.23,
      "currency": "USD",
      "visitCount": 3,
      "landingPage": "https://example.com/",
      "referrer": "https://referrer.com/page",
      "country": "US",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "utmParams": {
        "source": "utm_source",
        "medium": "utm_medium",
        "term": "utm_term",
        "content": "utm_content",
        "campaign": "utm_campaign"
      },
      "customData": {
        "1": "any string value",
        "2": "any string value"
      },
      "timestamp": "2025-04-09T12:34:56-07:00"
    }
  ]
}

Required Fields

Field	Type	Description
goalName	string	Name of the goal (e.g., “Signup Complete”).
userIdentifier	string	Unique ID for the user — can be an email, account ID, or internal token.

Optional Fields

Field	Type	Description
url	string	Page URL where conversion occurred.
value	number	Monetary amount for the conversion.
currency	string	ISO 4217 code (e.g., USD, EUR).
visitCount	integer	Number of pages visited before conversion.
landingPage	string	User’s first page on your site.
referrer	string	Referrer URL.
country	string	Two-letter ISO country code (e.g., US).
userAgent	string	Browser user-agent string.
utmParams	object	Optional UTM tracking data (source, medium, term, content, campaign).
customData	object	Up to 5 custom string fields for user or goal metadata.
timestamp	string (ISO 8601)	When the conversion occurred.

✅ Tip: You can batch multiple conversions (up to 25) in one request to reduce network overhead.

Troubleshooting & Tips

Status	Meaning	Fix
401 Unauthorized	Invalid or missing API key.	Check that your API key is active and included correctly.
400 Bad Request	Malformed JSON or missing required fields.	Verify your syntax and required fields.
429 Too Many Requests	You’ve hit rate limits.	Wait before retrying; respect rate limits.
—	Value tracking issue	Ensure currency is a valid ISO code (e.g., USD).

Summary

The Conversion Tracking API gives you flexible server-side goal tracking beyond standard Crazy Egg scripts.
Use it to:

• Integrate conversions from backend systems
• Measure ROI
• Link external signup or purchase events to your Crazy Egg reports