CRM Onboarding

The CRM Onboarding APIs allow you to sync account profiles (IB, Affiliate, Trader) and create trading accounts within the FYNXT Incentive Program. These endpoints are called from your CRM system to keep client data in sync.

Overview

The onboarding flow consists of two main steps:

Upsert Account Profiles — create or update IB, Affiliate, and/or Trader profiles for a CRM account.
Create Trading Account — link a trading server account to an existing client profile.

All CRM API requests require two headers: X-Tenant-Slug and X-Api-Key.

Authentication

All CRM API requests must include the tenant slug and per-tenant API key:

X-Tenant-Slug: {{tenantSlug}}
X-Api-Key: {{apiKey}}

Contact FYNXT to obtain credentials for your brokerage.

Upsert Account Profiles

Use this endpoint to create or update one or more profiles (IB, Affiliate, Trader) for a given CRM account. Sending the same crmAccountId again will update the existing record.

POST

/api/abstraction/crm/upsert-account-profiles

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

Request body fields

crmAccountId

string

required

Unique identifier for the account in your CRM system (e.g. "CRM-USER-09876").

accountStatus

string

required

Status of the CRM account. Accepted values: "Active", "Inactive".

tenantId

number

required

The FYNXT tenant identifier assigned to your brokerage.

actionDoneById

number

required

ID of the actor performing this action (e.g. 1 for the CRM system user).

actionDoneByName

string

required

Display name of the actor (e.g. "CRM").

actionDoneByEmail

string

required

Email address of the actor (e.g. "crm@gmail.com").

actionDoneByRole

string

required

Role of the actor. Typically "Broker".

profiles

array

required

Array of profile objects to create or update. Each profile must include a type field set to "IB", "Affiliate", or "Trader". See Profile Types for per-type fields.

Profile object fields

type

string

required

Profile type. One of "IB", "Affiliate", "Trader".

name

string

required

Full name of the client.

country

string

optional

Country of residence (e.g. "Canada").

contactEmail

string

required

Contact email address for this profile.

currency

string

optional

3-letter ISO currency code (e.g. "EUR").

status

string

required

Profile status. Accepted values: "Active", "Inactive".

address

string

optional

Physical address of the client.

dateOfBirth

string

optional

Date of birth in YYYY-MM-DD format.

kycStatus

string

optional

KYC verification status. E.g. "Verified", "Pending".

externalId

string

required

Your system's unique identifier for this profile (e.g. "EXT-TRADER-006"). Used to link back to your CRM records.

referredById

string

optional

The externalId of the IB or Affiliate who referred this client (e.g. "EXT-IB-001"). Required for Trader profiles that have a referrer.

referrallinkId

number

optional

The FYNXT referral link ID associated with this profile's acquisition.

isDeleted

boolean

optional

Soft-delete flag. Set to true to mark the profile as deleted. Defaults to false.

onboardingStatus

string

optional

Current onboarding stage. E.g. "Completed", "Pending", "InProgress".

Profile Types

The type field in each profile object determines how the profile is classified within the FYNXT Incentive Program:

Type	Description	Typical use
`IB`	Introducing Broker — a partner who refers clients directly and earns commissions on their trading activity.	Set `externalId` to your IB's unique ID. Other Traders/Affiliates can reference this via `referredById`.
`Affiliate`	Affiliate partner — earns commissions based on referred client activity, typically via marketing channels.	Same structure as IB. Use `referredById` to chain under a parent IB if applicable.
`Trader`	End client who trades on the platform. Can be referred by an IB or Affiliate.	Set `referredById` to the `externalId` of the referring IB or Affiliate.

Trading Account Creation

After a client profile has been created via the upsert endpoint, use this endpoint to attach a trading server account to that client. This links the live trading account to the FYNXT Incentive Program so commissions and events can be tracked.

POST

/api/abstraction/crm/crm/trading-accounts

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

Request body fields

tradeServerId

string

required

The FYNXT trade server identifier (e.g. "tsv_01knh7qz80e61tv085bqwf06y1").

externalClientId

string

required

Your CRM's unique identifier for the client who owns this trading account (e.g. "EXT-1246354327"). Must match the externalId of an existing Trader profile.

externalReferredById

string

optional

The externalId of the IB or Affiliate who referred this client (e.g. "EXT-5").

tradeLoginId

string

required

The login ID on the trading server (e.g. MT4/MT5 login number such as "110001").

currency

string

required

3-letter ISO currency code for the trading account (e.g. "USD").

status

string

required

Account status. Accepted values: "Active", "Inactive".

isDeleted

boolean

optional

Soft-delete flag. Defaults to false.

actionDoneById

number

required

ID of the actor performing this action.

actionDoneByName

string

required

Display name of the actor.

actionDoneByEmail

string

required

Email address of the actor.

actionDoneByRole

string

required

Role of the actor. Typically "Broker".

referrallinkId

number

optional

The FYNXT referral link ID associated with this trading account's acquisition.

Trading Account Update

Update an existing trading account with the same request shape used for creation. The account ID is passed in the URL path.

PUT

/api/abstraction/crm/crm/trading-accounts/{id}

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

Other trading account endpoints:

GET /api/abstraction/crm/crm/trading-accounts/{id}
GET /api/abstraction/crm/crm/trading-accounts
DELETE /api/abstraction/crm/crm/trading-accounts/{id}

CRM Accounts

Create or update the underlying CRM account record used by the onboarding flow. This is the account-level sync endpoint separate from individual profile records.

POST

/api/abstraction/crm/crm/accounts

Create a CRM account. Base URL: https://fynxt-incentive-program.hummingwave.com

PUT

/api/abstraction/crm/crm/accounts/{id}

Update a CRM account using the same body shape.

Request body fields

crmAccountId

string

required

Unique identifier for the CRM account.

status

string

required

Account status. Accepted values: "Active", "Inactive".

country

string

optional

Country associated with the CRM account.

timezone

string

optional

Account timezone, for example "UTC".

language

string

optional

Preferred language for the CRM account.

registrationDate

string

optional

Registration timestamp in ISO-8601 format.

Auxiliary Trade Data

Ingest auxiliary trade data for downstream commission and settlement processing.

POST

/api/abstraction/crm/trade-aux

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

Request body fields

crmTenantId

string

optional

Tenant identifier for the CRM account. Also accepted as crm_tenant_id, tenantId, and tenant_id.

tradeId

string

required

Unique trade identifier.

tradeLogin

string

required

Trading account login used for the trade.

tradingServerId

string

required

Identifier of the trading server.

spread

number

optional

Raw spread value for the trade.

markupSpread

number

optional

Spread markup applied by the broker.

markupCommission

number

optional

Commission markup applied by the broker.

Settlement Update

Send rebate settlement results back into the platform so completed payout batches can be reconciled.

POST

/api/abstraction/crm/api/settlements/settlement-update

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

Request body fields

batchReferenceId

string

required

Settlement batch identifier.

payouts

array

required

Array of payout update objects.

externalRefId

string

required

External payout reference for the IB or trader.

crmReferenceId

string

optional

CRM-side reference identifier.

status

string

required

Payout result status, for example "SUCCESS".

failureReason

string

optional

Reason supplied when the payout failed.

processedAt

string

optional

Processing time in ISO-8601 format.

Settlement Webhook

This is the outbound settlement callback we send after a reward settlement is committed. The same event is also published to Kafka topic settlement-topic.

This section is separate from the CRM request APIs above and uses the headers below as a suggested setup.

Authentication (Suggested)

Header	Description
`X-Tenant-Slug`	Identifies which tenant this event belongs to.
`X-Api-Key`	Per-tenant secret issued for the callback.

Payload

settlementBatchId

string

required

Batch identifier for the settlement run.

settlementEventId

string

required

Unique event identifier for idempotency.

settlementType

string

required

Settlement type, for example "REBATE".

tenantId

string

required

Tenant identifier.

ibCrmAccountId

string

optional

CRM account identifier for the IB.

programId

number

optional

Reward program identifier.

programName

string

optional

Reward program name.

settlementAmount

number

optional

Settlement amount.

settlementStatus

string

optional

Current settlement status, for example "PENDING".

settlementCurrency

string

optional

ISO currency code for the payout.

retryCount

number

optional

Number of delivery attempts.

ibInternalId

number

optional

Internal IB identifier.

invoiceId

string

optional

Invoice identifier, if available.

invoiceUrl

string

optional

Direct URL to the invoice PDF.

Delivery guarantees

At-least-once delivery is not guaranteed. On failure, the webhook is retried 3 times with backoff.
If you need guaranteed delivery, reconcile against Kafka topic settlement-topic or request a resend.

Expected response

Any 2xx status code is treated as success. Response body is ignored. Non-2xx or timeout triggers a retry.

Idempotency

The payload includes a unique event ID. Use it to deduplicate repeated deliveries.

Swagger Documentation

The full interactive API reference — including all request/response schemas, authentication details, and the ability to try requests directly in the browser — is available in the Swagger UI:

Open Swagger UI →

← Previous

REST API reference