REST API reference

The FYNXT Referral API is a conventional JSON-over-HTTPS REST API. Use it to create links, post conversion events, read clicks, and manage the postback endpoints that deliver those events to your downstream systems.

Base URL

https://fynxt-incentive-program.hummingwave.com

All endpoints are relative to this base URL.

Authentication

The API uses API keys. Pass your key in the X-API-Key header on every request. Contact FYNXT to obtain an API key for your brokerage.

X-API-Key: YOUR_API_KEY

Errors

Errors use conventional HTTP status codes and return a JSON body of the form:

{ "error": {
    "code":    "link_not_found",
    "message": "No referral link matches id ln_abc123.",
    "param":   "link_id"
}}

Status	Meaning
`400`	Validation error or malformed request.
`401`	Missing or invalid API key.
`403`	Key lacks permission for this resource.
`404`	Object does not exist.
`409`	Idempotency conflict.
`429`	Rate limit hit. Back off and retry.
`5xx`	Server error. Safe to retry.

Pagination

All list endpoints use cursor pagination with limit (1–100, default 25) and starting_after. Responses include has_more and the last object's ID as the next cursor.

Create a referral link

POST/api/referral/links

Creates a new referral link for a partner. The response returns the full URL to distribute, including any encrypted partner ID token.

partner_id

string

required

Identifier of the IB or affiliate that owns the link.

landing_page

string

required

Relative path on your site where visitors will land, e.g. /en/open-account.

encrypt_partner_id

boolean

optional

When true, the partner ID is emitted as Formx=... instead of ref=.... Default false.

utm

object

optional

Optional source, medium, campaign, term, content. Appended to the link query string.

region_routing

boolean

optional

When true, clicks are geo-routed to the closest regional domain.

Retrieve a link

GET/api/referral/links/:id

Returns the link with click and event counters for the last 30 days.

Post a conversion event

POST/api/referral/events/track

This is the core write endpoint. Call it (or let the JavaScript SDK call it) whenever a tracked action happens. FYNXT resolves attribution via the supplied clickId, records a referral_event, finds or creates a trader profile for the email address, and fans the event out to every subscribed postback endpoint.

event

string

required

One of REGISTRATION, VERIFICATION, KYC_COMPLETED, FIRST_DEPOSIT, FIRST_TRADE, RECURRING_DEPOSIT, WITHDRAWAL, ACCOUNT_UPGRADE, SUBSCRIPTION, EMAIL_SIGNUP, CONTENT_DOWNLOAD, WEBINAR_REGISTRATION, DEMO_ACCOUNT_CREATION, NEWSLETTER_SUBSCRIPTION, CUSTOM.

clickId

string

recommended

Click identifier issued at referral-redirect time and stored in the visitor's click-id cookie by the JavaScript SDK. Used as the primary attribution signal. Falls back to browser fingerprint / session matching when absent.

data

object

optional

Event-specific payload. Recognised keys:

email — string. Used to identify or create a trader profile.
name — string. Full name; used when creating a new trader profile.
amount — number. Monetary value for deposit or withdrawal events.
currency — string. 3-letter ISO currency code for amount.
paymentMethod — string. e.g. "card", "wire", "crypto".

metadata

string (JSON)

optional

Free-form JSON string, stored verbatim and echoed in the postback (max 2 KB).

List events

GET/api/referral/events

Filters: partnerId, eventType, clientId, isConversion.

The Event object

The response body from POST /api/referral/events/track (and embedded in postback deliveries) has this shape:

Field	Type	Description
`id`	number	Event ID.
`eventType`	string	See event types.
`clickId`	number	Attributed click ID.
`clientId`	number	Internal trader profile ID (auto-created from email).
`amount`	number	Monetary value, if supplied.
`currency`	string	ISO 4217 code.
`isConversion`	boolean	`true` if this event qualifies for a CPA payout.
`isDuplicate`	boolean	`true` if the same event type was already recorded for this trader.
`timestamp`	string (ISO 8601)	Event time in UTC.

List clicks

GET/api/referral/clicks

Returns clicks with full metadata — IP, country, device type, browser, UTM tags. Use this for attribution audits and fraud investigation.

Create a postback endpoint

POST/api/postback_endpoints

Registers a URL to receive postback deliveries. Returns the object and the signing_secret used to verify future deliveries — this is the only time the secret is returned in plaintext.

url

string

required

HTTPS URL to POST events to. Must respond 2xx within 10s.

enabled_events

array<string>

required

Event types to subscribe. Use ["*"] for all.

description

string

optional

Human-readable label shown in the dashboard.

metadata

object

optional

Free-form JSON. Useful for tagging endpoints by environment or team.

List postback endpoints

GET/api/postback_endpoints

Send a test event

POST/api/postback_endpoints/:id/test

Synthesizes a REGISTRATION event with fake data and delivers it to the endpoint. Useful for verifying signature handling during integration.

Delete a postback endpoint

DELETE/api/postback_endpoints/:id

Stops new deliveries and empties the retry queue. In-flight deliveries will complete.

No undelete. Dead-letter messages for a deleted endpoint are retained for 30 days in the dashboard but cannot be re-queued.

← Previous

JavaScript SDK

Back →

Postback introduction