Conversions API (CAPI) for Ad Platforms & DSPs

Overview and Core Concepts

What is Conversions API (CAPI)?

Conversions API is a server-to-server integration method that allows advertising platforms to receive conversion events directly from Freshpaint's backend systems. Unlike pixel-based tracking (which relies on browser requests), CAPI sends conversion data via HTTP POST requests to the ad platform's endpoint.

How CAPI Integrations Work

Architecture Overview

CAPI integrations follow a standardized flow:

Common Integration Pattern

Real-Time Event Collection

Events are sent immediately when conversions occur. Best for high-volume, time-sensitive campaigns where attribution latency matters.

CAPI Request Payload Structure

Below is a sample CAPI request body sent from Freshpaint to the Ad Platform.

POST /signal/v1/conversion HTTP/1.1
Host: px.dsp.com
Content-Type: application/json
Authorization: Bearer <API_TOKEN>
Content-Length: 1234

{
  "advertiser_id": 12,
  "conversion_type": "Page View",
  "data_source_key": "abc123def456",
  "event_id": "db0a5a9e030b93a12a4c4c6668b0d0474e673372beeab20efc00c6425f934069",
  "ids": [
    {
      "id": "85b04ded-09dd-4015-ad30-581e45452dd9",
      "name": "Guid"
    },
    {
      "id": "[email protected]",
      "name": "Email"
    },
    {
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
      "name": "HashedEmail"
    }
  ],
  "order_id": "t1GFlDxuBVNbgMylYUoJ3aaTZ0ymGWZ4W2V1BLNBfJVgV+pf6Er2xjDh+Gvacl8rDcyQaEwiYsO++JC4uEMTZg==",
  "user_agent": {
    "browser": "Chrome",
    "operating_system": "Mac OS X"
  },
  "timestamp": "2026-04-13T14:30:00Z",
  "value": 99.99,
  "currency": "USD"
}

Key Payload Components

HTTP Headers

Header	Required?	Description
Content-Type	Yes	Applicable content type Ex. 'application/json'
Authorization	Highly recommended	Bearer token or API key 'Bearer <token-or-key>'

Example JSON Body Fields

Field	Type	Description
advertiser_id	Integer	Unique identifier for your ad account on the platform
data_source_key	String	Identifier for this specific CAPI data source within your advertiser account
conversion_type	String	Type of conversion (ex, 'Purchase', 'Page View', 'Signup', 'Lead')
event_id	String	Unique identifier for this event (usually SHA-256 hash of user ID + timestamp)
ids	Array	Array of flat user identifiers objects of user identifiers, depending on platform (see below). At least one user is required.
user_agent	Object	Browser and OS information. Improves matching accuracy
timestamp	ISO 8601	When the conversion occurred (UTC). Default: now
value	Float	Conversion value (e.g., purchase amount). Use for ROAS calculations
currency	String (ISO 4217)	Currency code of the value (ex, 'USD', 'EUR'). Default: 'USD'
order_id	String	Unique order ID for deduplication across retries

`ids` Array

The 'ids' array contains objects with 'id' and 'name' fields representing different identifier types:

Identifier Type	Format	Example
Guid	UUID v4	85b04ded-09dd-4015-ad30-581e45452dd9
Email	Plain text, lowercase	[email protected]
HashedEmail	SHA-256 hex	a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Phone	Plain text, no formatting	14155552671
HashedPhone	SHA-256 hex	f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2
FirstPartyId	String, custom ID	customer_12345

---

4. Implementation Checklist

Pre-Integration

• Obtain advertiser_id and data_source_key from the ad platform

• Generate or request API token/bearer token for authentication

• Confirm CAPI endpoint URL with the ad platform

• Review ad platform's CAPI documentation for any custom field requirements

Integration Development

• Build conversion event capture logic in Freshpaint backend

• Implement payload construction with required fields

• Add user identifier collection and optional hashing (SHA-256)

• Implement authentication (Bearer token, API key signing)

Testing

• Test payload schema validation against platform requirements

• Verify authentication token is valid and included correctly

• Perform test conversions and confirm receipt on the ad platform

• Test identifier matching with known user accounts

• Verify retry behavior on network failures

• Confirm HTTP status codes (200, 201, 400, 401, 429, 5xx) are handled correctly

Post-Launch

• Monitor error rates and HTTP response codes

• Track conversion attribution in the ad platform dashboard

• Validate data completeness and accuracy

• Set up alerting for integration failures

---

5. Best Practices & Recommendations

Data Quality

• Provide at least one identifier per event. Multiple identifiers increase matching probability.

• Use consistent identifier formatting (lowercase email, no phone formatting).

• Include user_agent data to improve device and browser matching.

Reliability

• Ad platform should properly handle deduplication.

Security & Compliance

• Only accept HTTPS (TLS 1.2+) for CAPI requests.

---

Getting Started

To explore a destination integration partnership with Freshpaint, please reach out to our partnerships team at [email protected]. We're happy to walk through a technical overview, share our event schema documentation, and discuss what a partnership could look like for your platform.