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://api.fynxt.com/v1

Regional hosts — api-eu.fynxt.com, api-ap.fynxt.com — are available for data residency; ask your account manager to enable them.

Authentication

The API uses API keys. Pass them in the Authorization header as a bearer token. Secret keys (sk_live_...) are for server-side use. Publishable keys (pk_live_...) are read-only, safe to ship in browser bundles for the JavaScript SDK.

Authorization: Bearer sk_live_...

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/v1/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/v1/referral/links/:id

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

Post a conversion event

POST/v1/referral/events

This is the core write endpoint. Call it from your backend whenever a tracked action happens, and FYNXT will resolve it to the attributed click, record a referral_event, and fan it out to every subscribed postback endpoint.

event_type

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.

session_id

string

conditional

Value of the visitor's FYNXT_SESSION_ID cookie. Required if click_id is not supplied.

click_id

string

conditional

Click identifier captured server-side at redirect time. Overrides session_id when both are present.

client_id

string

optional

Your internal profile ID for the referred client. Required for any event that marks a conversion.

amount

number

optional

Monetary value for deposit, withdrawal or trade events.

currency

string

optional

3-letter ISO currency code for amount.

metadata

object

optional

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

idempotency_key

string (header)

optional

Pass Idempotency-Key to safely retry. Keys are honoured for 24 hours.

List events

GET/v1/referral/events

Filters: partner_id, event_type, client_id, created[gte], created[lte], is_conversion.

The Event object

Every event returned by the API (and embedded in postback deliveries) has this shape:

Field	Type	Description
`id`	string	Event ID, prefixed `evt_`.
`event_type`	string	See event types.
`click_id`	string	Attributed click.
`partner_id`	string	Owner of the attributed link.
`client_id`	string	Your profile ID.
`amount`	number	Optional monetary value.
`currency`	string	ISO 4217 code.
`is_conversion`	boolean	`true` if this event locks in a referral payout.
`timestamp`	int (unix)	Event time.
`metadata`	object	Your free-form payload.

List clicks

GET/v1/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/v1/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/v1/postback_endpoints

Send a test event

POST/v1/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/v1/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