Create a Referral

Create an invitation link that a partner uses to onboard and connect other WorldFirst accounts. The link mode controls how attributions are counted and whether the invited account grants authorization scopes back to the partner. On success the link is returned with status fixed to ACTIVE.
Request Parameters
requestIdstring
required
Idempotency key. Assign a unique value (e.g., UUID) per request; it must be unique within a partner. Repeating the same requestId returns the result of the first creation instead of creating a new link.
referralTypestring
required
Invitation link mode.

Valid Values:

CONNECTED_ONLY — Association-only mode. One link can attribute multiple registrations without requesting authorization.
AUTHORIZED — Authorized mode. One link, one directed invitation that also activates the specified authorization scopes.
authorizationScopearray
Authorization scopes that the invited account will grant to the partner. Required when referralType is AUTHORIZED; ignored for CONNECTED_ONLY. Maximum 10 elements.

Valid Values:

PAYOUTS_OPERATE — Permission to operate payouts (initiate payments).
BALANCES_QUERY — Permission to query balances.
validityDaysinteger
Number of days the link stays valid, counted from creation. Value range: 1–365. If omitted, the platform default validity applies. After expiry, status automatically becomes EXPIRED.
maxRegistrationsinteger
Maximum number of attributions allowed. Value range: 1 or greater. Effective only for CONNECTED_ONLY mode; if omitted, attributions are unlimited. For AUTHORIZED mode this field is ignored and the limit is fixed at 1.
externalRefstring
Partner-side reference number stored and echoed back as-is. Not used for idempotency matching.
Response Parameters
resultResult
API call result. See Result.
idstring
Unique identifier of the invitation link. Use this ID to query the link later.
statusstring
Current status of the link. Fixed to ACTIVE on successful creation.

Valid Values:

ACTIVE — Link is valid and can accept new attribution requests.
EXPIRED — Link has passed its validity period (terminal).
EXHAUSTED — Link has reached its attribution limit (terminal).
referralTypestring
Invitation link mode.

Valid Values:

CONNECTED_ONLY — Association-only mode.
AUTHORIZED — Authorized mode.
authorizationScopearray
Authorization scopes granted through this link. Returned only for AUTHORIZED mode.

Valid Values:

PAYOUTS_OPERATE — Permission to operate payouts.
BALANCES_QUERY — Permission to query balances.
inviteUrlstring
Full invitation link, including a non-enumerable random token. Share this URL with the account you want to invite.
usedCountinteger
Number of successful attributions so far. Starts at 0 at creation.
maxRegistrationsinteger
Maximum number of attributions allowed. Returned only for CONNECTED_ONLY mode when a limit was set at creation.
externalRefstring
Partner-side reference number. Returned only when it was provided at creation.
createdAtdatetime
Time the link was created, following the ISO 8601 standard. See Data Types.
expiresAtdatetime
Time the link expires, following the ISO 8601 standard. See Data Types.
Error Codes
resultCoderesultStatusresultMessageTroubleshooting
SUCCESSSsuccessN/A
PARAM_ILLEGALFIllegal parameters. Refer to the API documentation to verify the request parameters, then retry.Provide `authorizationScope` when `referralType` is `AUTHORIZED`. Ensure `validityDays` is within 1–365 and `maxRegistrations` is 1 or greater.
INVALID_ARGUMENTFThe argument is invalid.Check each field against its type and constraints (e.g., `authorizationScope` values, `referralType` enum).
PERMISSION_DENIEDFNo permission to perform this operation. Please verify the account status and configuration.Confirm the partner account is enabled for the Referral service.
ACCOUNT_STATUS_INVALIDFThe account status is invalid for this operation.Verify the partner account is active before creating a link.
SERVICE_NOT_ALLOWEDFThe requested service is not available for this account.Contact WF business to enable the Referral service for this account.
REPEAT_REQUESTFA duplicate request is detected. The previous request is being processed.Wait and retry with the same `requestId`, or query the result.
PROCESS_FAILFA general business processing failure occurred.Do not retry with the same parameters. Contact WF support if the issue persists.
Definition
POST /api/open/v1/referrals/create
Request
{
"requestId": "req_a1b2c3d4",
"referralType": "AUTHORIZED",
"authorizationScope": [
  "PAYOUTS_OPERATE",
  "BALANCES_QUERY"
],
"validityDays": 30
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"id": "20260801000000012345",
"status": "ACTIVE",
"referralType": "AUTHORIZED",
"authorizationScope": [
  "PAYOUTS_OPERATE",
  "BALANCES_QUERY"
],
"inviteUrl": "https://business.worldfirst.com/register?ref=Xa9Kd2p",
"expiresAt": "2026-09-01T00:00:00+08:00",
"createdAt": "2026-08-01T08:00:00+08:00",
"usedCount": 0
}