Skip to main content
Use the Gravity Conversions API (CAPI) to send conversions from your backend to Gravity.
Conversions and CPA campaigns need CAPI. Gravity launches a Conversions or CPA campaign only after it receives a live CAPI event for the campaign’s conversion event, or after you pass a test for that event in Events Manager. Pixel events don’t count. Use the pixel for browser activity and attribution context. Use CAPI for purchases, signups, leads, and other events that your backend confirms.
The Tracking CLI can help your AI agent prepare the CAPI setup in your project. This page gives the manual integration contract.

Why send conversions from the server

The Gravity pixel records page views and detects some conversions in the browser. A server event is more reliable for events that your backend confirms:
  • Delivery: the event does not depend on the browser.
  • Data: you can add customer email, phone, order details, and line items that the frontend does not have.
  • Deduplication: an event_id makes sure that Gravity counts the same conversion only once.
  • Offline conversions: you can send phone calls, in-store purchases, and CRM events.

How it works

  1. The Gravity pixel runs on your site and records the attribution context.
  2. At the conversion, your frontend reads window.gravityPixel.getCAPIData(). It sends the result to your backend with the order.
  3. Your backend confirms the action. Then it calls POST /gateway/events with the pixel data and the conversion details.

Before you start

  • A Gravity advertiser account.
  • Your Gravity API key. Find it in the Gravity dashboard in Settings → Organization. Only an owner or admin of the organization can see it. The API key is not the same as your pixel ID.
  • The Gravity pixel on your site, if you want browser attribution. See Pixel setup.
  • A backend that can keep the API key secret.
Keep the API key on your backend. Do not put it in browser code, in a mobile app, or in a public URL.

Step 1: Install the pixel

Add the pixel to every page, if it is not there yet:

Step 2: Read the pixel data at the conversion

When the user completes a conversion, call getCAPIData(). Send the result to your backend with the order:
You can call getCAPIData() at any time after the pixel loads. Before the user gives consent, it returns null, so keep the || {} fallback. If the user did not arrive from a Gravity ad, the attribution fields are null. Gravity still records the conversion, but it does not attribute it to an ad.If you do not use the pixel, read every Gravity parameter from the landing page URL and store it. See Click IDs on the landing page.

Step 3: Send the conversion from your backend

Node.js helper

Unreleased: @gravity-ai/tracking/server is not included in the published @gravity-ai/tracking@0.1.0 package. The helper examples in this section are a preview, not a working installation path today. Use the direct API integration below, or the published CLI’s browser-login setup plan, until the helper is released.
On Node.js 20 or later, install the same package used by the Tracking CLI. Import its server-only entry point in your backend, never in browser or mobile code:
Set GRAVITY_API_KEY in your server’s environment. After your backend confirms the action, call track():
Use the attribution handoff from Step 2. req accepts an Express/Node request or a Fetch Request. If your handler has already read the body, pass gravity from that parsed body as shown above. track() fills the event timestamp and website action source, reads available request context, hashes email and phone, and sends the event with a two-second default timeout. It resolves to { ok, eventId, status?, eventStatus?, testMode?, error? } instead of throwing, so a tracking failure does not fail the business action. With orderId, the default event ID is <eventName>:<orderId>. For other actions, supply a stable eventId. Keep the original eventTime on retries. Do not put email or other personal data in the event ID. Where the browser also sends the same event, give both senders the same event ID. CommonJS uses the same entry point:
For Stripe webhooks, save the browser handoff on the Checkout Session before the redirect. Preserve your existing metadata and add gravity: gravityMetadata(body.gravity), using gravityMetadata from @gravity-ai/tracking/server. For subscription checkout, also save it in subscription_data.metadata. The helper keeps the click IDs and page URL within Stripe’s 500-character metadata value limit. In the confirmed payment webhook, pass the saved value as gravity, the provider event’s original time as eventTime, and a stable object ID as eventId; the webhook request itself has no browser attribution. The server entry point does not load the CLI, parser or native keyring. Server-only deployments can install with npm install --omit=optional to exclude the optional OS keyring dependencies. Saved CLI login then needs a normal install; API-key authentication through GRAVITY_API_KEY still works without keyring, and credentials are never saved to a plaintext file.

Direct API integration

Add your order details to the pixel data. Then send a POST request to the Gravity gateway.
You can send email and phone in plaintext. The API normalizes and hashes them. If you hash an email yourself, remove the spaces at the start and end, and change it to lowercase. Then hash its UTF-8 bytes with SHA-256.
The cURL example has "test_event_code", so Gravity validates the event but does not record a conversion. Remove test_event_code when you go live. The response is HTTP 200 with a status for each event. See Response.

Request reference

POST https://api.trygravity.com/gateway/events

Authentication

Send your API key in a request header, either one of these:
If the request has no key, the response is 401 with API key required. If the key is not valid, the response is 401 with Invalid API key.
The ?api_key=YOUR_API_KEY query parameter is deprecated. Existing integrations keep working, but don’t use it for new ones: load balancers, proxies, and tools such as Segment write full request URLs, including the key, to their logs. Move existing integrations to a header.

Request body

Event fields

Event types

Gravity also knows these standard names: AddPaymentInfo, AddToWishlist, SubmitApplication, ViewContent, Search, CustomizeProduct, FindLocation, Donate, PageView, AppInstall, AppOpen, and InAppPurchase. You can also send a custom event name, for example "event_name": "DownloadWhitepaper".

User data fields

Attribution fields (from the pixel)

getCAPIData() adds these fields to user_data: Send the user_data object from getCAPIData() without changes, on every event. Don’t copy single fields out of it: Gravity needs the full set to attribute the conversion.

Click IDs on the landing page

When a user clicks a Gravity ad, Gravity sends them to your landing page and adds the click IDs to the URL as query parameters:
Gravity keeps the query parameters that are already in your landing page URL, and it also adds the UTM parameters that you set on the campaign. The pixel reads these parameters and stores them, so getCAPIData() returns them on later pages. Passing getCAPIData().user_data to your backend without changes is the easiest way to send all of them. If you do not use the pixel, capture the parameters yourself:
  1. When the user lands, read every Gravity parameter in the URL: grclid, grcpid, grpuid, gradid, grsig, graid, and oppref. Store each one that is present.
  2. Persist them with the user’s session, and with the user’s account when they sign up, so that you still have them for events days or weeks later.
  3. Send all of the stored parameters in user_data on every conversion event.
Don’t send only grclid. Send every Gravity parameter that you stored. If your tracking system needs the click ID in a parameter with a different name, put the {grclid} macro in your landing page URL or in a UTM value, for example https://yoursite.com/landing?subid={grclid}. Gravity replaces the macro with the click ID. Gravity also adds the grclid parameter.

Gravity click parameters

When a user clicks a Gravity ad, the landing page URL has the Gravity click parameters (grclid, grsig, grcpid, grpuid, gradid). Some clicks also carry graid, and some ad networks also pass oppref. Capture every parameter, store it, and send all of them with each conversion. oppref alone does not attribute a conversion in Gravity. Send it together with a Gravity identifier such as grclid or grcpid.

Send the Gravity IDs on every event

Every conversion event needs the stored Gravity parameters, not only the first one. Later-funnel events that your backend sends days or weeks after the click, such as an activation, a purchase, or a subscription renewal, must carry the same grclid, grcpid, grpuid, gradid, grsig, graid, and oppref values as the first conversion, together with em and client_ip_address. Store the parameters on the user’s account at signup, and read them back for each event that you send.

Device context (from the pixel)

getCAPIData() also returns a client_context object. It contains device and browser signals, for example: Send the full client_context object from your frontend to your backend. Then add it to the CAPI request without changes. Gravity uses these signals for attribution and bot detection.

Customer identity (from your backend)

Add these fields on your backend. Send em and client_ip_address on every event where you have them. They are expected on each event, not optional extras. Send the other fields when you collect them:
You can send em, ph, fn, and ln as plaintext. Gravity normalizes them and hashes them with SHA-256 for storage. A hashed value must be a 64-character hex string. Before you hash, trim and lowercase emails, and keep only the digits of phone numbers.
Send a phone number (ph) when you collect it and your consent rules permit it. Gravity can use the hash as an additional identity signal.

Custom data

Response

A normal request returns HTTP 200:
A normal request returns accepted for each event. Gravity stores and attributes the events in the background. In this response, attributed is always false, because attribution occurs later. Test mode processes the events at once and returns the other statuses.

Errors

Deduplication

Gravity deduplicates events by event_id and event_name in a 48-hour window. Gravity does not deduplicate an event that has no event_id.
  • Use one stable ID for each confirmed action. Your order ID is a good choice.
  • When you retry, send the same event_id, event_name, and event_time.
  • If the pixel and your server both send the same conversion, use the same event name and ID in both.

Batch events

You can send up to 1,000 events in one request. Add more objects to the data array. The normal response only confirms that Gravity accepted the events. Look in Events Manager to make sure that the events arrived.

Verify the integration

1

Send a test event

Send a request with "test_event_code": "TEST123". A valid event returns "status": "test_ok". Gravity does not store a conversion in test mode. TEST123 only checks the payload. It does not unlock the event for a Conversions campaign: see Pass a test in Events Manager.
2

Pass a test in Events Manager

Run the CAPI test in Events Manager for each event you want to use in a campaign. See Pass a test in Events Manager.
3

Send a real event

Remove test_event_code. Send a confirmed conversion from your backend. The response is HTTP 200 with "status": "accepted".
4

Look at the dashboard

Open Events Manager. Find a recent event on the Conversions API row. Then look for the conversion in your reports. An event can arrive and not match a Gravity ad.

Pass a test in Events Manager

A passed test unlocks the event for Conversions and CPA campaigns before any live event arrives. A test code that you make up, such as TEST123, checks the payload but doesn’t unlock the event.
  1. In Events Manager, select Set up tracking.
  2. In the CAPI test, enter the exact event name that your backend sends, then select Start test.
  3. Copy the test_event_code field that Events Manager shows. Add it at the top level of your CAPI request.
  4. Trigger the event from your backend. Keep Events Manager open until it shows Test passed.
  5. Remove the test_event_code field from your request.
Test events don’t count as conversions.

Check event quality

Events Manager scores the CAPI events of each event type from 0 to 10. The score measures how many of the signals that Gravity uses for matching and attribution your events carry. It doesn’t measure confirmed matches. To see it, open Events Manager and find the event type in the event list. Select its score to open the details. The details list each signal with the share of events that include it: Each signal shows Good (80% of events or more), Low (30% or more), or Missing (less than 30%). Time to send shows the median time from the action to Gravity receiving the event, rated Good, Slow, or Late by the share of events that arrive within an hour. Malformed email or phone hashes also lower the score. Under Next step, the details show the one change that would raise the score most, for example sending an email hash or a stable event_id. No changes needed means there is nothing to fix. The score covers the last 7 days of live CAPI events. Test events don’t count. The score refreshes up to once an hour, so a change to your integration can take an hour to show.

Troubleshoot

Next

Pixel setup

Install the Gravity pixel on your site.