Meta Offline Conversions API

Overview

Signals sends conversions that happened away from your website to Meta: in-store purchases, phone orders, bookings, and outcomes recorded in a CRM. Meta uses them to attribute conversions to your campaigns and to optimize delivery, even though nothing happened in a browser.

Use this destination when the conversion lives in a system Signals can read, such as a CRM, a file drop, a database or a warehouse.

If you are reporting a change in lead status rather than a completed sale, use Meta Conversions API for CRM instead. If the conversion happened on your website, use Meta Conversions API.

Platform documentationMeta offline conversions reference

Supported sources

Sources supported by Meta Offline Conversions API

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 Zithara 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 Business with a dataset, previously called an offline event set, created in Events Manager.
• Admin access to that Business and dataset, so you can grant Datahash permission.
• If you are connecting manually, a Dataset ID and an Access Token with permission to send events to that dataset.
• A Datahash Studio account with the target project selected.
• A source connected in the same project that maps the identifiers you want to match on. The identifiers and event details Meta receives come from that source mapping, not from this destination.

Authentication

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

Login with Facebook For Business

1. Click Login with Facebook For Business and continue on the Meta consent screen. Datahash receives your name and profile picture and ongoing access to the assets you share. It cannot post on your behalf.
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 events are written. Signals writes to one dataset per connection.

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. Meta accepts the event names your source sends.

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

Deduplication happens on the order ID. Where more than one event carries the same order ID, the conversion is counted once.

Signals takes that value from your source mapping, so it works as long as the same conversion always carries the same order ID. A file re-read, a replayed batch or an offline event that collides with a pixel event for the same purchase all resolve to one conversion.

Map a stable order ID for this to hold. The same conversion needs to carry the same value on every export, so that a file re-read or a replayed batch resolves to the conversion already counted.

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
Event time	Always. UNIX timestamp. Use the time of the conversion, not the time of upload.
Event name	Always.
Last modified date	Always.
Action source	Always. Where the conversion happened: one of phone_call, chat, physical_store, system_generated or other.
Email address	One of email address or phone number.
Phone number	One of email address or phone number. Up to three values.
Currency	Purchase events only. The three-letter currency code.
Value	Purchase events only.

Recommended

All of these raise the share of conversions Meta can match to a person who saw your ads.

Field	Format
First name	Letters only, lowercase, trimmed, no punctuation.
Last 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.
Order ID	Your own order reference, sent as a string. It is optional in the schema but it is what deduplication runs on, so the same conversion has to carry the same value on every export.
Content IDs	The product or SKU IDs in the conversion, as a list. They have to be the IDs used in your Meta catalog, or dynamic ads cannot retarget the product that was bought.
Content type	product when the IDs are individual items, product_group when they are variant groups.

Also worth mapping

Other optional identifiers: a second and third email address, gender, date of birth, postcode, an external ID of your own, the Facebook login ID and the Facebook click ID (fbc).

Other optional detail about the conversion: product name, category and quantity, number of items, item number, subscription ID, shop ID, delivery method, predicted lifetime value, store page ID, store code, brand page ID, and one custom parameter and value.

Best practices

• Map as many identifiers as your source holds. One of email or phone is 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.
• Use the conversion time as the event time rather than the upload time, or Meta will attribute against the wrong window.
• Deduplicate in your source before sending. A file exported twice is two conversions unless the order ID stops it.

Troubleshooting & FAQ

Validate Credentials fails. Re-check the Dataset ID and confirm the token has permission to send events to that dataset.

No events appearing in Events Manager. Confirm you selected the correct dataset during authentication, that a source is connected and sending, and allow time for delivery.

Duplicate conversions. The order ID is missing or changes between exports. See Deduplication.

Low Event Match Quality. Add more of the recommended identifiers and fix formatting at source. A value hashed after being formatted incorrectly will never match.

Conversions attributed to the wrong period. Check that the event time carries the time of the conversion and not the time the file was uploaded.

Delivery stopped. The Meta permission or access token may have been revoked or expired. Reconnect through Login with Facebook For Business, or provide a fresh token.