Query a Referral

Retrieve the current details of an invitation link by its ID, including its status and, for AUTHORIZED links with an attribution, the invited account. If the link has passed its validity period, the status is lazily refreshed to EXPIRED at query time.
Request Parameters
idstring
required
Unique identifier of the invitation link, returned by the Create a Referral endpoint.
Response Parameters
resultResult
API call result. See Result.
idstring
Unique identifier of the invitation link.
statusstring
Current status of the link. Refreshed to EXPIRED at query time if the validity period has passed.

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.
usedCountinteger
Number of successful attributions so far.
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.
invitedAccountInvitedAccount
Details of the invited account. Returned only for AUTHORIZED mode when an attribution record exists.
Show child parametersShow child parameters
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.Verify `id` exists and belongs to the calling partner.
INVALID_ARGUMENTFThe argument is invalid.Ensure `id` is a valid non-empty string.
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.
SERVICE_NOT_ALLOWEDFThe requested service is not available for this account.Contact WF business to enable the Referral service for this account.
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/query
Request
{
"id": "20260801000000012345"
}
Response
{
"result": {
  "resultCode": "SUCCESS",
  "resultStatus": "S",
  "resultMessage": "success"
},
"id": "20260801000000012345",
"status": "EXHAUSTED",
"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": 1,
"invitedAccount": {
  "accountId": "2088000000012345",
  "invitedAccountStatus": "SUCCESS",
  "authorizationConfirmed": true,
  "registeredAt": "2026-08-02T10:30:00+08:00",
  "confirmedAt": "2026-08-02T11:00:00+08:00"
}
}