15 October 2026

Plexo illustration for Facebook Conversion API: Four Required Fields, Then Test Events

Facebook Conversion API: Four Required Fields, Then Test Events

The Meta Conversions API is the server-side channel for sending conversion events to Meta. Use it alongside the Pixel, not instead of it. Doing so recovers conversions that browsers and blockers drop, and it gives Meta a more complete signal to optimise your ads against. This guide covers how it works, how to set it up, and how to check it.

TL;DR:

  • Choose a hosted partner when backend capacity is limited and speed matters; choose direct integration for custom events, payload control, and maintenance by your team.
  • Each server event needs event_name, event_time, user_data, and action_source; website purchases should also include the source URL, value, and currency.
  • Generate one stable event_id at conversion time, then send it with matching event_name values from Pixel and server to prevent duplicate counts.
  • Use Test Events before launch, then review diagnostics, deduplication, and Event Match Quality; a successful response alone does not prove reliable matching.
  • Normalize email and phone identifiers, hash them before transmission, keep access tokens on your server, and honor consent and withdrawal requests.
Plexo
Connect Tracking to Revenue Operations
Plexo aligns content, operations, and revenue, helping wellness brands address fragmented marketing strategies and improve decision-making with a live operating view.

Table of Contents

What the Conversions API is and how it works

The Conversions API (often shortened to CAPI) is a server-to-server interface. Instead of relying on a browser to fire a tag, your server sends the conversion event straight to Meta. Meta processes those events much like Pixel events, whether they come from your website, an app, a point-of-sale system or an offline source.

Every request goes to a destination: a dataset (or Pixel) that you create or select in Events Manager. You authenticate with an access token generated there. The token is a secret, so it lives on your server and nowhere else.

Each event you send carries a payload. The official API schema requires four fields:

  • event_name: what happened, such as Purchase or Lead.
  • event_time: when it happened, as a timestamp.
  • user_data: the identifiers Meta uses to match the event to a person.
  • action_source: where the action took place, such as the website, an app or a physical store.

Beyond those four, you add context. A purchase event usually includes custom_data such as value and currency. A website event should include the source URL so Meta knows which page the action came from.

CAPI supports the standard funnel events you already know from the Pixel: PageView, ViewContent, AddToCart, InitiateCheckout and Purchase. It also supports custom events for actions specific to your business, like a booked consultation or a membership upgrade. Which events you can use depends on the integration you choose and Meta’s schema.

Think of it this way. The Pixel is a witness standing in the customer’s browser. CAPI is your own records, sent from your back end. Both describe the same customer, but they see different things, and that difference is the reason to use both.

Meta Pixel vs Conversions API: how they differ and why you run both

The two tools collect data in different places, so each has blind spots the other covers. Here is how they split the work:

  • The Pixel runs in the browser. It captures browser-side identifiers such as the _fbp and _fbc cookies, and it reacts to what happens on the page in real time.
  • CAPI runs on your server. It sends events your back end has confirmed, such as a paid order or a submitted form, and it is not touched by ad blockers or dropped page loads.
  • The Pixel can miss events. Browser restrictions, blockers and a customer closing the tab before the tag fires all mean a real conversion never reaches Meta.
  • CAPI can lack browser context. On its own, it has no access to cookies unless you pass them through from the browser to your server.
  • Together they overlap. The same conversion can arrive from both sources, which is why deduplication matters.

The usual practical advice, reflected in Twilio’s Segment documentation, is to run both: the Pixel for browser activity and first-party browser identifiers, and CAPI for server-confirmed events that the Pixel fails to deliver. When both send the same conversion, you reuse a shared event ID so Meta counts it once. We cover that pattern in its own section below.

There is a practical effect on attribution and reporting. With the Pixel alone, your numbers undercount whatever the browser drops, and Meta’s optimisation learns from an incomplete picture. With both channels feeding the same dataset, reported conversions get closer to what actually happened in your business, and the delivery system has more to learn from.

One caution on expectations. CAPI changes how data is transported. It does not replace consent management or make unlawful data collection acceptable. You remain responsible for collecting and sharing data lawfully, a point we return to in the privacy section.

The two also differ in who maintains them. A Pixel is usually a snippet a marketer can paste in. CAPI needs somewhere to run: a server, a tag gateway or a partner platform. That is a real step up in effort, but a manageable one, and the integration options below show how to size it.

Why use the Conversions API now

The business case comes down to signal quality. Meta’s ad delivery learns from the conversion events it receives. When some of those events never arrive, the system optimises against a partial view of who is actually buying.

Recovering lost conversions. Browsers increasingly restrict third-party tracking, and ad blockers stop Pixel requests entirely. A customer can complete a purchase and never be reported. Because CAPI sends from your server, it can deliver server-confirmed events that browser blocking or dropped page loads prevent the Pixel from sending. For a small business with a modest ad budget, each recovered conversion is a stronger learning signal.

Better optimisation. More complete event data helps in two ways. First, campaigns optimising for purchases or leads see more of those outcomes. Second, richer identifiers on each event improve matching, so Meta can connect a conversion to the right ad interaction. We cover how to measure that with Event Match Quality later in this guide.

Choosing signals that matter. Before you build anything, decide which events your business actually optimises toward. A wellness brand might care about booked consultations and repeat orders far more than page views. Define those optimisation signals first, then implement them consistently through the server pipeline. Sending every possible event creates noise, not insight.

Future-proofing. Privacy restrictions have tightened steadily, and there is no sign of that reversing. A measurement setup built only on browser tags will keep eroding. Moving key events onto a server-side path means your most valuable data no longer depends on what a browser chooses to allow.

Connecting tracking to the business. CAPI is also the way to feed offline and back-office outcomes into Meta. If a lead turns into a paying client over the phone, that sale can be sent back as an event. Our write-up on offline conversion tracking goes deeper on that operations-first approach.

Direct integration or a partner solution: which should you choose?

You have two broad routes, and the right one depends on your engineering capacity and how much control you want.

Direct integration means your developers write code that calls the Conversions API endpoint. It gives you full control over events, payloads and timing. It also means backend development, secure secret storage, monitoring and retry handling are your responsibility. Meta publishes reference documentation and endpoints for this, and there are step-by-step guides with SDKs for Node.js, Python, Ruby, PHP and Java.

Partner or hosted integration means a platform handles the plumbing. Your e-commerce platform, tag manager, CDP or a dedicated gateway sends the events. This removes most of the coding and server maintenance, and token handling is built in. The trade-off is control: you are bound to what the partner supports, and custom events or unusual payloads can be harder to achieve.

Here is how the two compare in practice:

  • Speed: a partner can often be live relatively quickly; a direct build needs planning and developer time.
  • Control: direct wins for custom events, unusual data sources and precise payload shaping.
  • Maintenance: partners absorb most API changes; with a direct build, your team owns them.
  • Coupling: a partner ties you to its roadmap; a direct build ties you to your own codebase.
  • Cost: partners trade engineering hours for subscription fees; a direct build costs developer time up front and ongoing.

Choose a partner when speed matters and backend resources are thin. Choose direct integration when you need custom events, tight control over data, or you already run a server pipeline that can carry the load.

Pro Tip: Whichever route you take, write down which events you will send and who owns the access token before anyone writes code. Most delays come from unclear ownership, not from the API itself.

Step-by-step setup checklist for a basic web integration

This sequence works for a typical website running the Pixel already. Hand it to your developer or use it to brief a service provider.

  1. Create or select your dataset. In Events Manager, choose the dataset (Pixel) that will receive server events. For most web setups, this is the Pixel you already run, so browser and server events land in one place. Copy the dataset ID.
  2. Generate an access token. Create it in Events Manager. Meta does not store access tokens for you, as partner setup guides point out, so save it somewhere secure at once.
  3. Keep the token server-side. It belongs in server configuration or a secrets manager. It must never appear in front-end code, page source or a public repository.
  4. Decide your events. List the business actions you want Meta to optimise for, and map each to a Meta standard event name. Use custom events only where no standard event fits.
  5. Build the server request. Send events to the Conversions API endpoint with the four required fields: event_name, event_time, user_data and action_source. Add custom_data (value, currency, content details) where it applies.
  6. Include the source URL. For website events, pass the URL of the page where the action occurred.
  7. Add a shared event_id. Generate one stable ID per conversion and send it from both Pixel and server (see the deduplication section).
  8. Pass browser identifiers through. Capture the _fbp and _fbc values in the browser and forward them to your server so they can be included in user_data.
  9. Test before you trust it. Send events with a test_event_code and confirm them in Events Manager before judging campaign performance.

A few operational details separate a working integration from a reliable one:

  • Preserve the original event_time. If your server sends an event late, use the time the customer acted, not the time of sending. Accurate timestamps keep attribution honest.
  • Set action_source correctly. Website events, app events and in-store events are different, and mislabelling them muddies your data.
  • Batch sensibly. Sending events in groups reduces overhead, but each event still needs complete fields.
  • Plan for failure. Networks fail. Build retry handling so a temporary error does not silently lose a purchase, and log responses so you can see what Meta accepted.
  • Monitor continuously. An integration that worked on launch day can break after a site update. Check delivery periodically, not just once.

Platform guides such as AnyTrack’s setup documentation show the same operational steps in a hosted context: token generation and rotation, SHA-256 hashing of customer data, attaching fbc and fbp identifiers, event mapping and deduplication with event IDs. Even if you build directly, these are the steps to cover.

Not every integration is a web form. If you run a call-driven business, the same dataset can receive offline events. Invoca’s installation guide shows how call-tracking integrations reuse the existing Pixel or dataset and send hashed phone numbers as match identifiers. Plan for that early if phone enquiries are a major part of how you win customers.

Finally, keep your campaign attribution tidy alongside all of this. CAPI tells Meta what converted. Your UTM structure tells your own reports where it came from. Our guide to UTM tracking best practices covers how to keep the two consistent.

Deduplication: reuse one event_id to avoid double counting

When the Pixel and CAPI both report the same purchase, Meta needs a way to know it is one purchase, not two. The mechanism is the event_id.

The pattern is simple. Generate one stable event_id at the moment of conversion. Send it with the Pixel event in the browser, and send the same value with the server event. As long as the event_name and dataset also match, Meta treats the two as a single conversion and counts it once.

In practice, the cleanest approach is to create the ID on the server (or at the point of order confirmation) and pass it to the browser, so both sides read from one source. For example, you might use your order number, or a generated value stored with the order.

The mistakes that cause inflated counts are almost always the same:

  • Separate IDs. A common failure is generating one ID in the browser and a different one on the backend. The events are technically identical, but Meta sees two.
  • Mismatched event_name. If the Pixel sends “Purchase” and the server sends “purchase” or a custom name, deduplication fails.
  • Different destinations. Sending to two different datasets means the events are never compared.
  • Parallel setups. A partner plugin and a custom build both sending the same events, with no shared ID, will double count.

Deduplication also works in your favour. When one source misses an event, the other still supplies it. When both deliver it, Meta merges them. That is the whole point of running both channels: coverage without double counting.

Verify and diagnose: Test Events and Event Match Quality

Do not judge a CAPI setup by Ads Manager numbers alone. Test it where Meta shows you what it actually received.

Start with Test Events in Events Manager. Add a test_event_code to your server requests, send a sample conversion, and watch for it to appear and be labelled as a Server event. Partner documentation describes events showing up within roughly 30 seconds in one implementation, but treat that as specific to that integration, not a universal promise from Meta.

Then review the Overview and Diagnostics views. Look for:

  • Connection method: confirm events arrive via both browser and server.
  • Warnings and errors: missing parameters, invalid values or formatting problems appear here.
  • Deduplication status: confirm shared event IDs are being recognised.
  • Data quality notes: these point to identifiers you could add.

A successful HTTP response is not proof of success. Meta can accept an event and still be unable to match it to an ad interaction. That is where Event Match Quality comes in.

Event Match Quality (EMQ) reflects the customer identifiers you send with each event. Tealium’s connector documentation explains that improving EMQ means improving the quality and coverage of legitimately collected identifiers, such as hashed email and phone, rather than just switching a connector on.

A high EMQ score does not prove tracking is complete. Review it per event type, parameter coverage and browser and server overlap to find funnel events that are underreported.

Tools that read this data go further. Zernio’s API documentation describes returning event-level match keys and event coverage percentages, so a team can see which identifiers to add first. Use that kind of view to prioritise:

  • Hashed email and phone: usually the strongest identifiers when collected lawfully.
  • IP address and user agent: pass these through from the original visitor, not from your server.
  • Click and browser IDs: _fbc and _fbp, forwarded from the browser.
  • Consistency: the same identifier formats across every event.

Fix the identifier gaps on your highest-value events first. A small lift in matching on purchases or qualified leads is worth more than a perfect score on page views.

Best practices for data handling and privacy

Good CAPI data is clean, hashed and sent on time. The handling rules are precise, so follow them exactly.

Hash identifiers before sending. Normalise email and phone values (trim spaces, lowercase emails, standardise phone formats), then apply SHA-256 hashing. Never send raw personal information. AnyTrack’s guide lists SHA-256 hashing of customer data as a standard step in any integration.

Protect the access token. Store it on your server, restrict who can read it, and rotate it on a schedule or whenever staff with access leave. Meta does not store it for you, so a lost token means generating a new one.

Send accurate context. Include the correct action_source, the source URL, and the original timestamps. Preserve the visitor’s IP address and user agent where you legitimately hold them.

Use Limited Data Use flags where required. If privacy rules in your market or audience call for restricting how data is used, apply Meta’s Limited Data Use options.

Remember who is responsible. Server-side delivery changes how data travels, not whether you were entitled to collect and share it. Meta’s API model positions CAPI as an optimisation and measurement channel, not a substitute for consent management. Collect consent properly, honour opt-outs, and check the privacy rules that apply to your audience, including GDPR and CCPA where relevant.

Some sensitive verticals need extra care. Health and wellness businesses, for instance, should think hard about which parameters they pass. Call-tracking integrations, as Invoca’s guide notes, may strip some marketing parameters for sensitive categories. When in doubt, send less and send it cleanly.

Common issues and a troubleshooting checklist

Most CAPI problems fall into three buckets. Work through them in this order:

  • No events appearing. Confirm the dataset or Pixel ID is correct and the access token is valid and attached to that dataset. Then run Test Events with a test_event_code and check the response from Meta for error details.
  • Low Event Match Quality. Check how many events carry hashed email, phone, IP address and user agent. Look at uniqueness too: match keys that repeat or are blank do little to help matching. Add identifiers on your most valuable events first.
  • Duplicate or inflated counts. Verify that Pixel and server events share the same event_id and event_name. Then look for parallel setups, such as a plugin and a custom build, sending the same events without coordination, and remove one.
  • Events arriving late or with wrong times. Check that you send the original event_time, not the time of transmission.
  • Events mislabelled by source. Confirm action_source matches where the action actually happened.
  • Works in testing, fails after a site change. Re-run Test Events after every release that touches checkout, forms or tag setup.

If tracking disagrees with your Ads Manager numbers, resist the urge to trust either blindly. Our breakdown of the common Meta Ads mistakes covers measurement pitfalls that distort budget decisions.

Why CAPI belongs inside your operating system

Most CAPI projects fail for a boring reason: the events get sent, but nobody connects them to how the business is actually run. My view is that tracking only earns its keep when it feeds a live operating view of revenue and marketing performance. If purchase events land in Meta but your finance numbers, CRM and ad reports tell three different stories, you have added a pipe, not clarity.

So start small and start with money. Pick the two or three events that matter most, such as a paid order, a qualified lead and a booked appointment. Confirm each with test events before widening the rollout. Resist the urge to send everything. A short list of trusted signals beats a long list nobody has verified.

I also think teams underestimate how much a short, focused audit saves. Most misconfigurations I see described come from the same places: two systems sending the same event, a token nobody owns, identifiers that never get passed from browser to server. Those are operational gaps, not coding gaps. Fixing them once, with someone accountable, avoids months of quietly bad data.

— Jordan

How we help you get Conversions API tracking running

Your tracking is only as useful as the decisions it supports. At Plexo, we start with a focused business audit that finds the tracking and operational gaps holding your measurement back, then we stay on to implement the fixes with you.

Here is what that looks like in practice:

  • The audit: we review your events, datasets, tokens and reporting, and produce a tailored plan.
  • Token and security handling: we set up secure storage and an owner for your access tokens.
  • Event mapping: we match your business actions to Meta events and agree which ones matter most.
  • Deduplication: we make sure Pixel and server events share event IDs so nothing is double counted.
  • Verification: we confirm delivery in Test Events and work through Event Match Quality with you.

The audit is a one-off fee of 499 AUD, and the follow-on implementation is scoped to your business. If you want an executed plan rather than a document, book the Plexo Business Audit and we will take it from there. You can also see how we run integrated systems on our services and pricing page.

FAQ

How do I get API access from Facebook?

You generate an access token inside Events Manager for the dataset (Pixel) you want to send events to. Meta does not store the token, so copy it and keep it securely on your server straight away.

How do I set up the Conversions API?

Create or select your dataset, generate an access token, and send server requests with the required fields: event_name, event_time, user_data and action_source. Reuse one event_id across the Pixel and server events, then confirm everything in Test Events. A partner platform can handle the coding if you lack developer time.

Is the Meta Conversions API free?

The API itself is a documented Meta interface with published endpoints and SDKs. Your costs come from the build or from any partner platform you use to send events. Check your partner’s pricing, as it varies.

What are the key differences between the Meta Pixel and the Conversions API?

The Pixel runs in the browser and captures browser identifiers and on-page activity. The Conversions API runs on your server and sends confirmed events that blockers or dropped page loads can miss. Most advertisers run both and deduplicate with a shared event_id.

Sources

Newsletter

Back to blog