Gainsight PX

Datafly Signal delivers product-usage events to Gainsight PX server-to-server using the Custom Event API. Signal sends each tracked event as a PX custom event keyed on your own user identifier, so you can power product-experience analytics, adoption dashboards, and customer-health scoring without loading the client-side aptrinsic tag in the browser.

Signal integrates with Gainsight PX (the product-experience analytics product), which exposes a server-side ingestion API. Gainsight CS (Customer Success) does not have a real-time event-ingest API and is not covered here.

Prerequisites

Before configuring Gainsight PX in Signal, you need a PX subscription, a REST API key with write access, and your PX product key.

Step 1: Find Your PX Product Key

Sign in to Gainsight PX.
Go to Administration > Products.
Copy your Product Key (format AP-XXXXXXXXXX-2). This is the propertyKey Signal sends with every event.

Step 2: Create a REST API Key

In Gainsight PX, go to Administration > Integrations > REST API.
Click Create API Key.
Enable the Write permission (required to create custom events). Read-only keys are rejected with a 403.
Copy the key value. It is sent as the X-APTRINSIC-API-KEY request header.

⚠️

Store the API key securely. A key without the Write permission cannot create events.

Step 3: (Optional) Pre-register Custom Events

Some PX plans require custom events to be declared before they accept data. If your events do not appear after sending, go to Administration > Events and create the custom event names you map below (for example Feature Used, Subscription Started).

Configure in Signal

Configuration Fields

Field	Required	Description
`api_key`	Yes	PX REST API key with Write permission. Sent as the `X-APTRINSIC-API-KEY` header.
`property_key`	Yes	Your PX product key (`propertyKey`), e.g. `AP-XXXXXXXXXX-2`.

Management UI Setup

Go to Integrations > Add Integration > Gainsight.
Choose the B2B / SaaS preset for the standard product-usage funnel.
Enter your api_key and property_key.
Click Save.

API Endpoint

POST https://api.aptrinsic.com/v1/events/custom
X-APTRINSIC-API-KEY: {api_key}
Content-Type: application/json

Each event is sent as a single JSON object. The required fields are identifyId, propertyKey, userType, and eventName.

If your PX subscription is on EU data residency, the host may be region-specific. Contact Datafly support if your events 404 against the default host.

Identity Signals

Gainsight PX is a first-party product-analytics tool: events are matched to a user by your own user identifier, not by hashed PII or advertising cookies.

Signal	PX field	Description
`user_id`	`identifyId`	Your logged-in user’s stable identifier. Required — events without it are dropped.
—	`userType`	Set to `USER` for identified traffic. Can be `LEAD` or `VISITOR` for unauthenticated actors.
`account_id` (trait)	`accountId`	The PX account the user belongs to, for account-level rollups and health scoring.
`context.session.id`	`sessionId`	Session identifier for sessionised analytics.
`context.page.url`	`url`	Page URL where the event occurred.

How to Identify Users

Call datafly.identify() when a user logs in so Signal has a user_id (and account) to attach to every event:

datafly.identify("user-123", {
  account_id: "acct-987",
  email: "jane.doe@example.com",
  plan: "enterprise"
});

Event Mapping

B2B / SaaS preset

Signal event	Gainsight PX event
`page`	`Page Viewed`
`Signed Up`	`Signed Up`
`Logged In`	`Logged In`
`Feature Used`	`Feature Used`
`Products Searched`	`Searched`
`Plan Viewed`	`Plan Viewed`
`Trial Started`	`Trial Started`
`Subscription Started`	`Subscription Started`
`Subscription Cancelled`	`Subscription Cancelled`

Event properties are nested under the PX attributes object, where they become the custom event’s properties. To customise, edit the integration’s Field Mappings in the Management UI.

Example: Feature Used Event

Datafly.js call:

datafly.track("Feature Used", {
  feature_name: "Bulk Export",
  category: "Reporting",
  value: 1
});

Gainsight PX payload sent by Signal:

{
  "identifyId": "user-123",
  "propertyKey": "AP-XXXXXXXXXX-2",
  "userType": "USER",
  "eventName": "Feature Used",
  "date": 1717689600000,
  "sessionId": "sess-abc123",
  "accountId": "acct-987",
  "url": "https://app.example.com/reports",
  "attributes": {
    "featureName": "Bulk Export",
    "category": "Reporting",
    "value": 1
  }
}

The date field is the event time in epoch milliseconds (a Long), as required by the PX Custom Event API.

Testing Your Integration

Send a test event

Trigger a tracked event on your site (for example a login or feature click) for a user you can identify.

Verify in Gainsight PX

In Gainsight PX, go to Analytics > Events.
Filter by the event name (for example Feature Used).
Confirm the event appears against the expected user, with your custom attributes populated.

Check the user timeline

Open the user in Audience Explorer and confirm the event shows on their activity timeline.

Troubleshooting

Problem	Solution
Events not appearing	Confirm the API key has the Write permission, and the `property_key` matches your PX product. Some plans require the custom event to be pre-registered under Administration > Events.
`401` / `403` responses	The API key is invalid or read-only. Regenerate a key with Write access.
`400` responses	A required field is missing — every event needs `identifyId` (from `user_id`), `propertyKey`, `userType`, and `eventName`. Ensure users are identified via `datafly.identify()`.
Wrong event time	`date` must be epoch milliseconds. Check the event timestamp in Signal’s event debugger.
Events missing for anonymous users	PX events require an identifier. Anonymous traffic is dropped unless you map an anonymous identifier and set `userType` to `VISITOR`.

Rate Limits

Limit	Value
Requests per second	~200
Requests per day	~1,000,000

Signal applies a per-integration rate limit slightly under the documented ceiling to avoid throttling.

GoHighLevel Microsoft Dynamics 365