Meta Conversions API for CRM

Overview

Signals sends updated lead information from your CRM back to Meta, so campaigns running against Meta native lead forms can optimize towards leads that became qualified rather than towards raw form fills.

Use this destination when a lead is captured in a Meta lead form and its outcome is recorded somewhere else: a CRM, a file drop, a database or a warehouse. Signals reads the lead status from that system and reports it to your Meta dataset.

Once set up, lead events sync from your source every 15 minutes. Meta calls the resulting optimization Conversion Leads, and you may see this integration referred to as Meta Conversion Leads or Meta CLO.

If the conversion is a purchase or a booking rather than a change in lead status, use Meta Offline Conversions API instead.

Platform documentationMeta Conversions API reference

Supported sources

Sources supported by Meta Conversions API for CRM

Category	Supported
API	Datahash API
CRM	ActiveCampaign Agile Apptivo Attio Bexio Bitrix24 Capsule Close Coevera Copper Freshsales HubSpot Insightly Kommo LeadSquared Microsoft Dynamics Monday Odoo Pipedrive Salesforce VTiger Zoho
Database	Apache Cassandra ClickHouse CockroachDB Couchbase CouchDB IBM DB2 MariaDB Microsoft SQL Server MongoDB MySQL Oracle PostgreSQL
File & storage	Files - AWS S3 Files - GCP Files - FTP Google Drive Microsoft OneDrive Box Dropbox Filebase BackBlaze Cloudian DigitalOcean Linode MinIO OVHcloud Tencent Vultr Wasabi
Warehouse	Amazon Redshift Google BigQuery Snowflake

Prerequisites

Before connecting you need:

• A Meta Ads account.
• A Meta Business Manager account with access to the dataset you intend to send to.
• Server-side API permission on that dataset.
• If you are connecting manually, a Dataset ID and an Access Token generated in Events Manager. See Authentication for where to find both.
• A Datahash Studio account with the target project selected.
• A source connected in the same project. The identifiers and lead details Meta receives come from that source mapping, not from this destination.

Lead status events go to a dataset configured to receive CRM events, not to your website dataset. Create one before you connect, and note the Dataset ID as you go.

1. In Events Manager, click Connect Data Sources, select CRM, then click Connect.
2. Choose whether to create a new dataset or convert an existing one. Creating a new one is recommended, so CRM events do not mix with your website events and troubleshooting stays simple.
3. Enter the name of the CRM you are using, then choose to connect the API yourself. Datahash handles the integration, so you do not need the developer instructions Meta offers.
4. Check the dataset now shows the CRM indicator in Events Manager, confirming it is ready to receive CRM events.

This step adds the Conversion Leads Optimization workflow to the dataset. Without it, Meta will accept the events but campaigns cannot optimize against them.

Authentication

In Studio, open Destinations, find Meta, and click the Conversions API for CRM tile. You can connect in two ways.

Login with Facebook

1. Click Login with Facebook and continue on the Meta consent screen.
2. Select the business and the dataset you want to send events to, and grant the requested permissions.
3. You are returned to Studio with the account connected. Click Finish.

Manual setup

1. Enter your Dataset ID and Access Token.
2. Click Validate Credentials.
3. Click Finish.

Field	What it is	Where to find it
Dataset ID	The unique identifier Meta assigns to a dataset created in Events Manager.	business.facebook.com, then All tools, Events Manager, Data Sources, select your dataset, Settings.
Access Token	A credential authorizing Datahash to send events to that dataset on your behalf.	The same Settings screen, scroll to the Conversions API section, choose Set up manually, then Generate Access Token.

Caution

Keep access tokens secure. Never share one outside the Datahash connection screen.

Configuration

The dataset you chose during authentication is where lead events are written. It must be the CRM dataset created above, not your website dataset, or campaigns will not be able to optimize against the events.

The events themselves come from the connected source. Event names, the identifiers used for matching and the deduplication key are all set by the source mapping, not here.

There is no event mapping on this connector. The lead status you send becomes the event name in Meta.

Manage instance

To change the instance, open it from the Manage existing instance table, click the edit option in the menu to the top right, update the fields and click Finish.

Deduplication

The event ID is what deduplicates. Where the same event ID and event name arrive against the same dataset, the conversion is counted once.

Signals builds that event ID from the Meta lead ID and the last modified date. A lead re-synced without changing produces the same event ID and is counted once. A genuine status change produces a new last modified date, and so a new event ID, and is counted as a new conversion.

The match window is 48 hours against the same dataset. Because that is short relative to a CRM lifecycle, keep backfills and replays deliberate: a record re-sent more than 48 hours after its first delivery is counted as a new conversion.

Data & identifiers

Signals sends the fields your source maps into the Offline Event Schema. Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach Meta.

Required

Field	When it is required
Meta lead ID	Always. The 15 or 16 digit ID Meta generated when the lead form was submitted, taken from the leadgen_id field in the lead generation webhook.
Lead status	Always. The name of the status, for example Interested.
Event time	Always. UNIX timestamp.
Last modified date	Always. The time the lead status was updated.
Lead source	Always. The name of the system the leads come from, for example HubSpot, Dynamics, Oracle or an in-house CRM.
Action source	Always. One of phone_call, chat, physical_store, system_generated or other.
Email address	Always.
Phone number	At least one, up to three.
Currency	Purchase events only. The three-letter currency code.
Value	Purchase events only.

Recommended

All of these raise the share of leads Meta can match.

Field	Format
First name	Letters only, lowercase, trimmed, no punctuation.
City	Letters only, lowercase, trimmed, no punctuation.
State or region	In the US, the two-character code in lowercase. Elsewhere, the region name in lowercase with no punctuation or spaces.
Country	The two-letter country code in lowercase, for example gb or in.

Optional

Field	Format
Additional email addresses	Up to two more, one address each.
Last name	Letters only, lowercase, trimmed, no punctuation.
Gender	A single letter: f or m.
Date of birth	DD/MM/YYYY.
Postcode	Lowercase, no spaces. In the US, the first five digits only.
External ID	A unique ID of your own, such as a loyalty membership or user ID.

Best practices

• Map as many identifiers as your source holds. Email and phone are required; name and location are the cheapest way to lift match rates beyond that.
• Keep formatting clean at source: lowercase email, phone in E.164, no stray whitespace. Hashing a badly formatted value produces a hash that will never match.
• Send only the lead stages worth optimizing towards. Reporting every status change dilutes the signal Meta learns from.
• Make sure the last modified date actually updates when the record changes, since it is what separates one status change from the next.
• Set the lead source to the system the leads actually come from. It tells Meta where the outcome was recorded, and it is required.

Troubleshooting & FAQ

Validate Credentials fails. Re-check the Dataset ID. Confirm the token was generated for that dataset and not a different one, and that the account has server-side API permission.

No events appearing in Events Manager. Confirm a source is connected in the same project and is sending. Events reach Meta through the source, so a connected destination on its own produces nothing.

Leads rejected or unmatched. Check that the Meta lead ID is populated. Without it Meta cannot tie the update to the original lead form submission.

Duplicate conversions. Usually a backfill or replay sent more than 48 hours after the original delivery. See Deduplication.

Low match rate. Add more of the recommended identifiers and check formatting at source. A value that is hashed after being formatted incorrectly will never match.

Events arrive but campaigns will not optimize for them. The dataset is probably not configured for CRM events. Check it shows the CRM indicator in Events Manager, and see Prerequisites for how to create one.

Delivery stopped. The access token may have expired or been revoked. Generate a new one in Events Manager and re-validate the connection.