Event tracking

Report referral conversions from your backend: deposits, KYC approvals, first trades and anything else your servers know about first.

Before you start

trackEvent is part of the same FynxtCrmClient used for CRM onboarding. Copy the client and build it once as described in Install, Authentication and Initialize the client. Your tenant CRM key is accepted here; partner logins are not.

Tracking an event

Calls POST /api/referral/events/track.

fynxt.trackEvent(new TrackEventRequest()
    .event(EventType.FIRST_DEPOSIT)
    .brokerId(84650L)
    .clickId(client.getReferralClickId())
    .email("j.vane@partner-support.io")
    .amount(new BigDecimal("2500.00"))
    .currency("USD"));

Request fields

event

EventType

required

What happened. See Event types.

brokerId

Long

required

Your FYNXT tenant id (e.g. 84650). It must match the tenant of your API key; any other value, or none, is refused with 403.

clickId

String

optional

The click id of the referral link the client arrived through. Strongly recommended server-side: see Attribution.

clientId

Long

optional

FYNXT’s internal id of the client’s Trader profile (not your externalId). Wins over email.

String

optional

The client’s email, used when clientId is not set. See Identifying the client.

name

String

optional

The client’s name, used only if FYNXT creates a Trader profile from email.

amount

BigDecimal

optional

Monetary value, for deposits, withdrawals and subscriptions.

currency

String

optional

3-letter ISO code for amount.

metadata

String

optional

A JSON object as a string, stored with the event, e.g. {"paymentMethod":"wire"}.

Identifying the client

FYNXT links the event to a Trader profile in this order:

clientId: that profile, if it is a Trader. Otherwise the event has no client.
email: the Trader in your tenant with that contact email.

An unknown email creates a profile. If no Trader has that contact email, FYNXT creates a new Trader profile with a generated externalId. Send the same email you set as contactEmail during onboarding, or one client ends up with two profiles.

Attribution

FYNXT credits the event to the partner whose referral link the client clicked. With a numeric clickId it uses that click directly. Without one, it falls back to the caller’s session and device fingerprint, which describe your server, not the client, when the call comes from your backend.

So capture the click id when the client arrives: the JavaScript SDK stores it in the click-id cookie, and the referral redirect carries it as the click-id query parameter. Save it on the client record at sign-up, and send it with every server-side event.

Event types

Event	When to send
`REFERRAL_INITIATED`	A visitor lands from a referral link. The JavaScript SDK sends this one itself; you rarely need it server-side.
`EMAIL_SIGNUP`	The visitor submits an email on the first sign-up step.
`ACCOUNT_CREATION`	An account is opened, for example a demo account.
`REGISTRATION`	Full registration completes and a live client record exists.
`VERIFICATION`	Email or phone verification completes.
`LOGIN`	The client signs in.
`FIRST_DEPOSIT`	The first deposit settles on the live account. Send `amount` and `currency`.
`RECURRING_DEPOSIT`	A later deposit settles. Send `amount` and `currency`.
`FIRST_TRADE`	The first trade executes on the live account.
`RECURRING_TRADE`	A later trade executes.
`KYC_COMPLETED`	KYC passes and the client is fully approved.
`WITHDRAWAL`	A withdrawal is processed. Send `amount` and `currency`.
`ACCOUNT_UPGRADE`	The client moves to a higher account tier.
`SUBSCRIPTION`	The client subscribes to a paid plan.
`CUSTOM`	Anything else. Describe it in `metadata`.
`CONTENT_DOWNLOAD`	The visitor downloads gated content.
`WEBINAR_REGISTRATION`	The visitor registers for a webinar or live event.
`NEWSLETTER_SUBSCRIPTION`	The visitor opts in to marketing email.

Response

trackEvent returns a TrackEventResult; data() is the recorded event:

Field	Meaning
`id`	FYNXT’s id for the event.
`clientId`	The Trader profile it was linked to, or `null`.
`clickId`	The referral click it was attributed to, or `null` when no partner was credited.
`conversion`	`true` when this event type counts as a conversion for the attributed program.
`duplicate`	`true` when this client (or, without a client, this click) already had an event of this type. It is still recorded, but does not count toward partner metrics again.
`eventType`, `amount`, `currency`, `timestamp`	As recorded.

Retrying a failed call is safe for one-off events such as FIRST_DEPOSIT: a repeat comes back with duplicate set.

Error handling

Status	Meaning
`400`	Malformed request, for example an `event` value outside `EventType`.
`401` / `403`	Missing or wrong API key, a partner login, or a `brokerId` that is not your tenant.
`5xx` / `0`	Server or network failure. Retry with backoff.

Like every client method, failures throw FynxtApiException (see Error handling).

← Previous

Java SDK: Settlement