Skip to main content
NewNMC’s advertising guidelines for doctors are in force from 6 Oct 2026. See what to change, and get a free compliance auditNew NMC advertising rules for doctors: what to change
Paid Ads

Conversions API for Clinics: A Minimal Event Schema That Survives Meta's Health Filters

A practical specification for clinic Conversions API events: which to send, which parameters to hash, how to deduplicate with the Pixel, and what to leave out entirely.

Conversions API for Clinics: A Minimal Event Schema That Survives Meta's Health Filters

This is a specification for health tech teams and developers who are wiring a clinic or hospital website to Meta's Conversions API. It assumes you know what server-side tracking is. It answers a narrower question: what is the smallest set of events and parameters worth sending, and what should never leave your server?

The design goal is not to pass as much data as possible. For a health provider, the goal is to send enough for Meta to match a visitor and deduplicate an event, while sending nothing that reveals a condition, a treatment or a patient. If an event is later restricted for your data source, a minimal schema also means you have little to unpick.

Everything below is a proposal to be reviewed with your clinical lead and legal adviser. Meta's rules can change, and the parameter reference is the authority.

Principles before the schema

Meta's policy position is that advertisers are responsible for what they send, and that data revealing health information about people is prohibited. The Conversions API does not change that. Read the Meta help page on restricted information and the parameter documentation before you build.

Three principles follow.

  1. Send actions, not conditions. "Appointment form submitted" is an action. "Submitted a form for a named diagnosis" is a condition. Only the first is a candidate.
  2. Send identifiers for matching, never clinical context. Hashed contact details and browser identifiers help Meta match. Reason for visit, department of a specific procedure or symptoms do not belong in any field.
  3. Treat the restriction as possible. Design so the campaign still functions if the lower-funnel event is limited. See our earlier Meta health and wellness restrictions article for how the restriction tiers work.

The minimal event list

EventWhen to sendNotes
PageViewEvery page loadBrowser Pixel; mirror server-side only if you need it
ViewContentGeneric service or doctor page viewedDo not attach a condition or procedure name
ContactClick on phone, WhatsApp or directionsAction only
LeadAppointment or callback form submittedMay be limited for your source; send only if permitted
ScheduleAppointment confirmed in the booking systemOptional; only if it can be sent without clinical detail

Resist the temptation to add custom events named after treatments or symptoms. Each one is a disclosure. If your analytics team needs that level of detail, keep it in your own analytics, not in an ad platform.

Required fields on every server event

The Conversions API reference lists the core fields. For each event you send:

  • event_name: one of the standard names above.
  • event_time: Unix timestamp of when the action occurred.
  • event_id: a unique string you generate once and share with the Pixel for deduplication.
  • action_source: where the action took place, such as website.
  • event_source_url: the page URL, which should itself be free of condition names.
  • user_data: the customer information block described next.

If a lower-funnel event is restricted, remember that custom parameters and URL detail can be stripped. Do not rely on them to carry meaning.

The user_data block: hash what must be hashed

Meta's customer information parameter reference separates fields that must be hashed from those that must not.

Hash with SHA-256 after normalising: em (email), ph (phone), fn, ln, ct, st, zp, country, db and ge. Normalise first: trim, lower-case emails, and format phone numbers with the country code and no leading zeros. For an Indian mobile number, that means the country code followed by the ten digits.

Do not hash client_ip_address, client_user_agent, fbc and fbp. The reference says the IP address must never be hashed.

external_id is recommended to be hashed. Use an internal identifier that is not a medical record number or any identifier a hospital would use clinically. A random lead ID generated by your CRM is better.

For a clinic, a pragmatic minimum is em or ph, plus fbp, fbc when a click ID is present, client_ip_address, client_user_agent and external_id. Leave out db and ge. They add little to matching for appointment leads and they are personal details you do not need to transmit.

Deduplicate Pixel and server events

If you run both the browser Pixel and the server API, the same action will arrive twice. Meta's deduplication documentation explains the rule: an event is treated as a duplicate when the Pixel's eventID matches the API's event_id and the event name matches event_name. Deduplication applies within 48 hours of the first event with that ID.

Implementation notes:

  • Generate the ID once in the browser when the action happens, pass it to the Pixel as the fourth argument of the fbq call, and send it to your server in the form submission.
  • Never generate a fresh ID on the server for an action the browser already reported. That guarantees duplicates.
  • The fallback, matching on event_name plus fbp or external_id, works only when the browser event arrives first. Do not design around it.
  • Two server events with the same content from the same source are both kept. Deduplication does not remove double-submits from your own system, so debounce form submissions.

Want this applied to your practice? Get a free paid ads audit.

Book my free audit

What to leave out, explicitly

Write this list into the technical spec so a future developer does not "improve" the integration.

  • Page titles or URLs that include a condition, symptom or procedure.
  • Custom parameters containing department, doctor specialty tied to a condition, appointment reason or insurance details.
  • Free-text form fields of any kind.
  • Medical record numbers, patient IDs or claim numbers, even hashed.
  • Anything from a logged-in patient portal.
  • Test results, prescriptions and billing data.

Treat the disallowed list as permanent, even if a rule seems to allow more at the moment.

Check match quality without looking at patients

Events Manager shows an event match quality score for each event and the parameters Meta received. Use it as a diagnostic, not a target.

  1. Open the dataset and the event. Review which customer parameters Meta reports receiving.
  2. Compare the share of server events carrying fbc and fbp with browser events. A low match often means cookies are not being passed to your server.
  3. Send a test event with the test event code and confirm that the browser and server copies show as deduplicated rather than counted twice.
  4. Check timestamps. Events sent a long time after the action are less useful, and Meta's reference limits how old an event may be.
  5. Watch for sudden changes after site releases. A tag manager change is a common cause.

Do not chase a perfect score by adding sensitive or unnecessary parameters. A good score that required more disclosure is a worse outcome than an average score with a clean payload.

Hypothetical payload shape

A Lead event from an appointment form could carry: event_name: Lead, a timestamp, an event_id shared with the Pixel, action_source: website, a neutral source URL such as the appointment page, and user_data with hashed email, hashed phone, hashed external_id, fbp, fbc when present, IP address and user agent. No custom data block at all. That absence is deliberate.

Failure modes to test for

Most Conversions API problems in a clinic setting are quiet. The integration appears live, events arrive, and the numbers are still wrong.

  • Double counting after a form redesign. The new form fires the Pixel event on click and the server event on submit, with different IDs. Test the submit path end to end after every release.
  • Missing cookies on the server. If fbp and fbc are read in the browser but never posted with the form, the server event loses its best matching keys. Pass them as hidden fields or read them from the request cookies.
  • Wrong phone formatting. A number hashed with spaces, a plus sign or a leading zero will not match the same number hashed correctly. Normalise before hashing and unit-test the function with several Indian number formats.
  • Hashing twice. If a plugin hashes a value and your code hashes it again, the result matches nothing. Check whether your tag manager or plugin already hashes.
  • Proxy IP addresses. Behind a load balancer, the IP your server sees may be the proxy, not the visitor. Read the forwarded address your host provides, and confirm it with a test.
  • Retries that resend. A job queue that retries a failed request can send the same event repeatedly. Reuse the original event_id on every retry.
  • Consent ignored. If a visitor declines marketing cookies, the server must not send their data either. Tie the server call to the same consent state as the browser tag.

Write each of these as a test case. A clinic integration is rarely touched, so the tests protect the next developer.

Governance

Assign an owner for this schema. Review it with the clinical lead when the website adds a service or a new form. Log every change to the event list. For consent handling and first-party measurement, read our guide on server-side tracking and consent for healthcare, and see the conversion tracking service for implementation support.

Where to start

  • Freeze the event list at five or fewer.
  • Write the leave-out list into the spec.
  • Hash and normalise customer fields server-side.
  • Share event_id between Pixel and server.
  • Test with the test event tool before going live.
  • Re-verify the schema against Meta's documentation every quarter.
Filed underconversions API for clinicsmeta conversions api healthcaremeta capi event schemacapi deduplication event_idevent match quality clinic

About the author

Co-Founder & CTO · Gurugram, India

Arush builds the systems the rest of the company runs on — the patient-acquisition pipelines, the AI chatbots, the analytics that tie a single click to a booked appointment. If a campaign reports a number, it's because something his team built is tracking it.

Free guide · 15 pages

The Patient Acquisition Blueprint

A 90-day plan from first search to booked appointment.

The Pioneers Brief — one essay, three benchmarks, one teardown, every Thursday. Subscribe free →

Free paid ads audit

Your next chapter starts with a conversation.

Three quick questions. We come prepared with a plan for your specialty and city.

  • A 30-minute call with a healthcare specialist
  • Your top three growth opportunities, in writing
  • Honest advice — even if that means not hiring us
  • No obligation and no hard sell
You’ll speak with a senior strategist
Consultations are hosted by Arush Thapar’s team.
Step 1 of 3Takes 30 seconds

What do you want to improve first?

Details stay privateNo obligationReply within 1 working day

Client portfolio · Healthcare websites

Work relevant to conversions api for clinics a minimal event schema that survives.

Explore client work →