Meta Conversions API

Send server-side conversion events to Meta’s Conversions API for improved attribution accuracy. Server-side events bypass browser ad blockers and cookie restrictions, giving you more reliable measurement and optimization data for Meta ad campaigns.

Prerequisites

A Meta Business Manager account
A Pixel set up in Meta Events Manager
Your Pixel ID (numeric)
A Conversions API access token (or OAuth credentials)

Authentication

Access Token (Recommended)

Navigate to Meta Events Manager and open Data Sources
Select your Pixel from the list
Go to the Settings tab
Scroll down to the Conversions API section
Click Generate Access Token, copy the token, and paste it into the Access Token field in SignalSmith

OAuth 2.0

Click Connect with OAuth in SignalSmith
Sign in with your Meta Business account
Authorize the requested permissions

OAuth grants ads_management and ads_read scopes. Tokens refresh automatically but expire after 60 days if not used.

Configuration

Field	Type	Required	Description
Pixel ID	Text	Yes	Your Meta Pixel ID from Events Manager
API Version	Select	Yes	Meta Graph API version. Options: v19.0, v18.0, v17.0. Default: v19.0
Action Source	Select	Yes	Where the conversion events originate. Options: `website`, `app`, `email`, `phone_call`, `chat`, `physical_store`, `system_generated`, `other`
Test Event Code	Text	No	Test event code from Events Manager for validating events without affecting real data

Supported Operations

Sync Modes

Mode	Supported
Insert	Yes
Update	—
Upsert	—
Mirror	—

Audience Sync Modes

Mode	Supported
Add	Yes
Remove	—
Mirror	—
Upsert	—

Features

Feature	Supported
Field Mapping	Yes
Schema Introspection	No

Required Mapping Fields

Field	Description
`event_name`	The conversion event type (e.g., `Purchase`, `Lead`, `AddToCart`)
`email` or `hashed_email`	User identifier for matching. Provide either a raw email (auto-hashed by SignalSmith) or a pre-hashed SHA256 email

Default Destination Fields

Event

Field	Description
`event_name`	The conversion event type
`event_time`	Unix timestamp of the event
`external_id`	Your unique identifier for the user

User Data (raw)

These fields are automatically hashed with SHA256 before being sent to Meta.

Field	Description
`email`	User email address
`phone`	Phone number with country code
`first_name`	First name
`last_name`	Last name
`city`	City
`state`	State or province
`zip`	Zip or postal code
`country`	Two-letter country code

User Data (pre-hashed)

These fields are passed through to Meta without additional hashing. Values must be lowercase SHA256 hex strings.

Field	Description
`hashed_email`	SHA256-hashed email address
`hashed_phone`	SHA256-hashed phone number
`hashed_fn`	SHA256-hashed first name
`hashed_ln`	SHA256-hashed last name
`hashed_ct`	SHA256-hashed city
`hashed_st`	SHA256-hashed state
`hashed_zp`	SHA256-hashed zip code
`hashed_country`	SHA256-hashed country code

Custom Data

Field	Description
`value`	Monetary value of the event
`currency`	ISO 4217 currency code (e.g., `USD`, `EUR`)
`content_ids`	Array of product or content IDs
`content_type`	Category of content (e.g., `product`, `product_group`)
`order_id`	Your unique order or transaction identifier

Supported Event Types

Meta recognizes the following standard conversion events:

Purchase
AddToCart
Lead
ViewContent
CompleteRegistration
InitiateCheckout
AddPaymentInfo
Search
Subscribe
StartTrial
Contact
FindLocation
CustomizeProduct
Donate
SubmitApplication

Custom event names are also supported. Use any string as the event_name to track events specific to your business.

How It Works

SignalSmith reads rows from your model query and applies field mapping to transform your data into Meta’s Conversions API format.

PII hashing: Raw user data fields (email, phone, first_name, last_name, city, state, zip, country) are automatically normalized and hashed with SHA256 per Meta’s requirements before being sent. Pre-hashed fields (hashed_email, hashed_phone, etc.) are passed through without re-hashing.

Batching: Events are batched up to 1,000 per API call to POST /{api_version}/{pixel_id}/events. For syncs with more than 1,000 events, SignalSmith automatically splits them into multiple API calls.

Action source: The action_source value from your configuration is applied to every event in the sync.

Minimum requirements: Each event requires at minimum an event_name, event_time, and at least one user data field for matching (e.g., email or hashed_email).

Testing Events

Use the Test Event Code to validate your event setup before going live.

In Meta Events Manager, navigate to your Pixel and open the Test Events tab
Copy the test event code displayed at the top of the page
Paste the code into the Test Event Code field in your SignalSmith destination configuration
Run a sync — events appear in the Test Events tab in Events Manager without affecting your real campaign data
Verify that events are received correctly, fields are mapped properly, and match quality meets your expectations
Remove the test event code from your SignalSmith configuration before switching to production

Event Match Quality

Meta assigns each event an Event Match Quality score from 1 to 10 based on the amount and accuracy of user data you provide. Higher scores lead to better ad attribution and optimization.

To improve your Event Match Quality:

Include as many PII fields as possible — email, phone, name, and location fields all contribute to the score
Ensure proper formatting — emails should be lowercase, phone numbers should include country codes (e.g., +14155551234)
Include external_id if available — this provides an additional matching signal
Include event_source_url and client_user_agent for web events — these improve match accuracy for website conversions

Rate Limits

1,000 events per API call — SignalSmith automatically batches events to stay within this limit
Meta Graph API rate limits apply — standard rate limits are based on your app’s usage tier
For high-volume syncs, events are split into multiple sequential API calls

Best Practices

Maximize user data fields — include as many PII fields as possible to improve Event Match Quality and attribution accuracy
Test before production — use the test event code to validate your setup in Events Manager before sending real conversion data
Use event timestamps from your data — map event_time to the actual conversion timestamp in your warehouse, not the sync execution time
Include currency with value — always map currency alongside value for Purchase events to ensure correct revenue reporting
Use consistent external_id values — send the same external_id for the same user across all events to help Meta deduplicate and build accurate user profiles

Troubleshooting

Invalid Pixel ID

Verify your Pixel ID in Meta Events Manager under Data Sources. The ID should be numeric. Ensure you are using the Pixel ID, not the Ad Account ID or Business Manager ID.

Permission denied

Regenerate your access token in Events Manager and ensure it has the correct permissions for the Pixel. If using OAuth, verify the authenticated user has Admin or Advertiser access to the Pixel in Business Manager.

Low Event Match Quality

Your Event Match Quality score is low when too few user data fields are included. Add more PII fields to your mapping — email, phone, first name, last name, city, state, zip, and country all contribute to the score.

Events not appearing in Events Manager

Check that the Test Event Code is removed from your configuration if you expect events in the live view. Verify that the action_source matches your actual event source (e.g., website for web conversions). Events may take a few minutes to appear in Events Manager.

Duplicate events

Ensure your model query uses unique primary keys so the same event is not sent multiple times. Verify that event_time is mapped correctly — incorrect timestamps can cause Meta to treat events as duplicates or fail deduplication.

Token expired

Access tokens generated in Events Manager do not expire by default, but tokens created through other methods may. If you receive authentication errors, regenerate the token in Events Manager or switch to OAuth for automatic token refresh.

Events rejected by Meta

Check the API response errors in your sync logs. Common causes include missing required fields (event_name or event_time), invalid action_source values, or malformed user data. Ensure all mapped fields contain valid data.

Hash mismatch errors

If using pre-hashed fields (hashed_email, hashed_phone, etc.), ensure values are lowercase SHA256 hex strings. Do not mix raw and pre-hashed versions of the same field — use either email or hashed_email, not both.

Facebook Ads Meta Product Catalog