# 📈 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


```json
[
  {
    "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.