Signals API Documentation
Learn how to send server-side events directly to ad platforms using the Signals Gateway API.
Signals Gateway lets you send conversion events directly to ad platforms like Meta, TikTok, and Google without setting up server-side GTM. It's the fastest way to improve your attribution data.
Direct Integration
Send events via simple HTTP POST
Secure & Private
API key authentication, HTTPS only
Multi-Platform
One API, all major ad platforms
Get your API key
Create an API key from the Signals Gateway page. Keep it secure - you'll need it for authentication.
Connect your platforms
Link the ad platforms you want to send events to (Meta, TikTok, Google, etc.).
Send events
POST conversion events to our API endpoint. We'll route them to all connected platforms.
Include your API key in the X-API-Key header with every request. API keys start with 'capi_' and should be kept confidential.
X-API-Key: capi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxKeep your API key secret
Never expose your API key in client-side code. Always make API calls from your server.
https://api.getcapi.co/api/v1/eventsHeaders
| Header | Required | Description |
|---|---|---|
| Content-Type | Required | Must be application/json |
| X-API-Key | Required | Your GetCapi API key |
| Field | Type | Required | Description |
|---|---|---|---|
| event_name | string | Required | Standard event name (e.g., Purchase, Lead, PageView) |
| event_type | string | Required | Either 'conversion' or 'engagement' |
| container_id | string | Required | Your GetCapi container ID |
| payload | object | Required | Event-specific data (value, currency, items, etc.) |
| user_data | object | Optional | User identifiers for matching (email, phone, etc.) |
| event_id | string | Optional | Unique ID for deduplication |
| event_time | number | Optional | Unix timestamp in milliseconds |
| metadata | object | Optional | Additional custom data |
User Data Fields
| Field | Description | Example |
|---|---|---|
| User's email address (will be hashed) | customer@example.com | |
| phone | Phone number in E.164 format | +1234567890 |
| external_id | Your internal user ID | user_123 |
| first_name | User's first name | John |
| last_name | User's last name | Doe |
| fbp | Facebook browser pixel cookie | fb.1.1234567890.1234567890 |
| fbc | Facebook click ID cookie | fb.1.1234567890.AbCdEfGhIj |
curl -X POST https://api.getcapi.co/api/v1/events \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"event_name": "Purchase",
"event_type": "conversion",
"container_id": "YOUR_CONTAINER_ID",
"payload": {
"value": 99.99,
"currency": "USD",
"transaction_id": "txn_123456"
},
"user_data": {
"email": "customer@example.com",
"phone": "+1234567890",
"external_id": "user_123"
},
"event_id": "evt_unique_123",
"event_time": 1704067200000
}'PageView
User viewed a page
ViewContent
User viewed specific content/product
AddToCart
User added item to cart
InitiateCheckout
User started checkout process
Purchase
User completed a purchase
Lead
User submitted lead form
CompleteRegistration
User completed registration
Subscribe
User subscribed to service
Contact
User submitted contact form
Search
User performed a search
Success Response (201 Created)
{
"id": "evt_abc123",
"event_name": "Purchase",
"event_type": "conversion",
"status": "success",
"webhooks_triggered": 3,
"created_at": "2024-01-01T12:00:00Z",
"is_duplicate": false
}Error Response
{
"detail": "Container not found or you don't have access to it"
}| Status Code | Description |
|---|---|
| 201 | Event created successfully |
| 200 | Duplicate event detected (already processed) |
| 400 | Invalid request body or missing required fields |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have access to container |
| 404 | Container not found |
| 429 | Rate limit exceeded |
The API implements rate limiting to ensure fair usage. Check these headers in responses:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed per window |
| X-RateLimit-Remaining | Requests remaining in current window |
| Retry-After | Seconds to wait before retrying (on 429) |
Default Limits
Free plan: 100 requests/minute. Pro plan: 1,000 requests/minute. Enterprise: Custom limits available.
We automatically deduplicate events based on the event_id field. If you send the same event_id twice within 48 hours, the second request will return 200 instead of 201, and the event won't be processed again.
Best Practice
Generate a unique event_id for each event. A good pattern is combining a timestamp with a random string:
event_id: `evt_${Date.now()}_${Math.random().toString(36).slice(2)}`Event Tester
Use our built-in Event Tester to send test events and see real-time results.
Open Event TesterNeed Help?
Our support team is here to help you integrate.