Meta (Facebook) Conversions

This guide covers how to submit offline conversions to Meta (Facebook) through the TNT Growth API.

Authentication

All requests require an x-api-key header with your client-specific API key provided by TNT Growth.

-H "x-api-key: YOUR_API_KEY"

Submitting a Conversion

Endpoint

POST /api/meta/conversions/add

Request Body Schema

Field	Type	Required	Description
metaPixelId	string	Yes	Your Meta Pixel ID (provided during onboarding)
eventName	string	Yes	The conversion event name (e.g. Purchase, Lead)
eventTime	number	No	Unix timestamp (seconds) of when the event occurred
actionSource	string	No	Where the event originated — website or phone_call
eventSourceUrl	string	No	The URL where the event took place
eventId	string	No	A unique ID for deduplication (recommended)
testEventCode	string	No	Meta test event code for verifying in Events Manager
userData	object	No	Customer identifiers for matching (see below)
customData	object	No	Key-value pairs for conversion details (e.g. value, currency)
utmSource	string	No	UTM source parameter (e.g. google) — stored for attribution reporting
utmMedium	string	No	UTM medium parameter (e.g. cpc) — stored for attribution reporting
utmCampaign	string	No	UTM campaign name — stored for attribution reporting
utmTerm	string	No	UTM search keyword — stored for attribution reporting
utmContent	string	No	UTM content parameter (ad/creative variant) — stored for attribution reporting

User Data Fields

Include as many identifiers as possible to improve match quality.

Field	Type	Description
email	string	Customer email address
phone	string	Customer phone number
firstName	string	Customer first name
lastName	string	Customer last name
clientIpAddress	string	IP address of the customer
clientUserAgent	string	Browser user agent string
fbp	string	Facebook browser pixel cookie
fbc	string	Facebook click ID cookie
city	string	Customer city
state	string	Customer state or region
country	string	Customer country (ISO 3166-1 alpha-2)
postal_code	string	Customer postal/ZIP code

Example Request

curl -X POST https://flex.tntgrowth.io/api/meta/conversions/add \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "metaPixelId": "123456789012345",
    "eventName": "Purchase",
    "eventTime": 1778043599,
    "actionSource": "website",
    "eventSourceUrl": "https://example.com/thank-you",
    "eventId": "order-12345",
    "userData": {
      "email": "customer@example.com",
      "phone": "+15551234567",
      "firstName": "Jane",
      "lastName": "Doe",
      "fbc": "fb.1.1612345678.AbCdEfG"
    },
    "customData": {
      "value": 150,
      "currency": "USD"
    },
    "utmSource": "facebook",
    "utmMedium": "paid-social",
    "utmCampaign": "retargeting-q2",
    "utmTerm": "rehab-centers",
    "utmContent": "carousel-ad-variant-b"
  }'

Example Response

{
  "message": "Conversion successfully queued for Example Client",
  "data": {
    "submissionId": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c"
  }
}

Checking Submission Status

After submitting a conversion, use the submission ID to check processing status.

Endpoint

GET /api/conversions/submissions/:submissionId

Example Request

curl https://flex.tntgrowth.io/api/conversions/submissions/8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
  "id": "8f3c2d10-7e6b-4a51-9d8c-3b2e1f0a9b8c",
  "source": "META",
  "externalAccountId": "123456789012345",
  "expectedCount": 1,
  "createdAt": "2026-05-11T12:00:00.000Z",
  "scheduledFor": null,
  "counts": {
    "success": 1,
    "failed": 0
  },
  "status": "complete"
}

Status Values

Status	Description
pending	Conversion is queued and waiting to be processed
pending_delivery	Submission is scheduled for future delivery — the scheduledFor field carries the ISO-8601 fire timestamp. Currently only emitted by Google Ads ingest paths; Meta submissions never enter this state.
complete	Conversion processed successfully
complete_with_errors	Processing finished but some conversions failed — use GET /api/conversions/meta/failed?submissionId=<id> to fetch the actual error messages
stalled	Processing has not progressed — contact support

The scheduledFor field is always null for Meta submissions and is included only for schema parity with Google Ads, which uses it for deferred delivery.

Inspecting Failed Conversions In Your Batch

When a submission ends with complete_with_errors, the submission status endpoint surfaces only the count of failed rows. Fetch the actual error messages with:

GET /api/conversions/meta/failed?submissionId=<submissionId>

The response payload mirrors the Google Ads failed-conversion shape — see Google Ads → Inspecting Failed Conversions In Your Batch.

Common Event Names

Event Name	When to send
Purchase	Customer completes a purchase
Lead	Customer submits a lead form
AddToCart	Customer adds an item to their cart
ViewContent	Customer views a key page (e.g. pricing, product)
AddPaymentInfo	Customer enters payment information
InitiateCheckout	Customer begins the checkout process
CompleteRegistration	Customer completes account registration

Best Practices

• Include eventId for deduplication — if the same event is sent twice with the same eventId, Meta will deduplicate it
• Send userData with as many identifiers as possible to maximize match rates
• Use accurate timestamps — eventTime should reflect when the event actually occurred, not when you're sending it
• Include fbp and fbc cookies when available — these provide the strongest matching signal for web events
• Poll with a delay — wait 30-60 seconds after submission before checking status
• Events older than 7 days will be permanently rejected by Meta