Skip to content
Last updated

📈 Tracking Conversions with the LettrLabs API

Use the /v1/conversions endpoint to send a list of conversion events. This allows LettrLabs to perform matchback attribution between direct mail and real-world outcomes like sales or signups.

📤 Endpoint

POST /v1/conversions

Sends multiple conversion events in a single request. The system will validate each record and return detailed feedback per item.

🧠 Principles for Best Results

  1. ✅ Provide at least one piece of identifiable information
    Acceptable identifiers include:

    • primaryEmail / secondaryEmail
    • primaryPhoneNumber / secondaryPhoneNumber
    • address (address1, city, state, zip)
    • couponCode

  2. 🔍 The more information you provide, the better the match accuracy.
    Including multiple identifiers increases the likelihood of correctly linking the conversion to a mailed recipient.

  3. 💰 Every conversion must include a revenue amount
    Use the revenue field to specify the value of the conversion event.

  4. 🕒 Provide an event date in UTC
    Use the eventDate field to indicate when the conversion occurred.
    If omitted, the current time will be used — this is only recommended for real-time event-driven systems.

  5. 🆔 Use Unique ID and CRM ID for passthrough tracking
    Fields like uniqueId and crmId are recommended for connecting conversion records back to your internal CRM or customer journey systems after exporting data from LettrLabs.

  6. 🛑 Provide Order ID to avoid duplicates
    If orderId is not provided, each event is treated as a unique record — even if it’s a duplicate submission.

  7. 👤 Customer ID helps tie conversions to users
    Use customerId if available. This improves tracking and aggregation accuracy.

  8. 🔁 Primary vs. Secondary Identifiers
    You can use primary and secondary versions of address, email, and phone fields. There is no difference in how they match — they are useful for different data models (e.g., billing vs. shipping, personal vs. business).

📝 Request Example

[
  {
    "firstName": "John",
    "lastName": "Smith",
    "primaryEmail": "john@example.com",
    "primaryPhoneNumber": "1234567890",
    "primaryAddress": {
      "address1": "123 Main St",
      "city": "Denver",
      "state": "CO",
      "zipCode": "80202"
    },
    "revenue": 249.99,
    "eventDate": "2025-06-01T15:23:00Z",
    "orderId": "ORDER-123",
    "couponCode": "SUMMER25",
    "uniqueId": "abc-xyz-789",
    "crmId": "crm-999",
    "customerId": "cust-001"
  }
]

✅ Response

Returns a summary including:

  • Total records
  • Valid and invalid records
  • Details on validation errors/warnings (if any)

🧪 Validation Logic

  • Records with missing revenue or all identifiers will be rejected.
  • Invalid addresses will not be matchable.
  • You may submit partial records, but accuracy may suffer.

🛑 Error Handling

  • 422 - All records invalid. Check Metadata for detailed issues.
  • 400 - Malformed request.
  • 401 - Invalid or missing API key.

LettrLabs uses the submitted conversion data to power analytics, attribution models, and ROI insights for your direct mail campaigns.

Previous page
Next page