# 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
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": "user@example.com",
"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 \'
|
#### 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 | `user@example.com` |
| 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 ****. 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.
\
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://documentation.freshpaint.io/integrations/partnering-with-freshpaint/conversions-api-capi-for-ad-platforms-and-dsps.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.