Referral by player

Looks up a group member by their playerId and returns their referral codes, plus the paginated list of referrals attributed to that member’s codes.

The playerId here identifies the group member by their externalRef: the identifier you supplied for that creator when you generated their code or linked their Nexus account. It is not the id of the player being referred; that value appears separately on each item in referrals.

Pass excludeReferralList=true to skip the referral history and get back only the member summary and codes. When set, currentPage, currentPageSize, totalCount, and referrals are left out of the response entirely.

Authorizations

X-SHARED-SECRET

required

stringheader

Send your public API key (nexus_pk_...) in the X-SHARED-SECRET header. Generate one in the Publisher Dashboard.

Parameters

Path Parameters

playerId

required

string

Example

player_8f2c41d0

Your identifier for this group member (their externalRef), the same value you supplied when you generated their code or linked their Nexus account. Not the id of the player being referred.

Query Parameters

groupId

string

Example

V1StGXR8_Z5jdHi6B1LiO

Creator group to use for this operation. If your key is scoped to a single program, that group is always used regardless of this value; otherwise falls back to your default group when omitted.

page

integer format: int32

default: 1 >= 1 <= 9999

page of records to return

pageSize

integer format: int32

default: 100 >= 1 <= 100

Maximum number of records to return

excludeReferralList

boolean

Example

true

If set to true, referrals are not retrieved and the response omits currentPage, currentPageSize, totalCount, and referrals entirely.

Responses

200

Referral code info requested

application/json

object

groupId

ID of the creator group

string

groupName

Name of the creator group

string

referralCodes

Array<object>

object

code

string

isPrimary

Indicates whether or not this is the primary Referral Code for this user.

boolean

isGenerated

Indicates whether or not this is a code that you generated.

boolean

isManaged

Indicates whether or not this is a code that you manage. Once a code that you generated has been linked to a Nexus account, it will no longer be considered managed.

boolean

playerId

Your identifier for this creator (their externalRef), the same value you supplied when you generated their code or linked their Nexus account. Not the id of the player being referred.

string

currentPage

Page number of response records returned

integer format: int32

currentPageSize

Page size used for this operation

integer format: int32

totalCount

Total number of referrals for this code

integer format: int32

referrals

Array<object>

object

The referral’s unique id.

string

code

The creator’s referral code.

string

playerId

ID of the referring player. This is not displayed to the nexus being referred

string

playerName

Display name of the referring player. This is displayed to the nexus being referred

string

referralDate

string format: date-time

400

Bad request

application/json

object

code

CodeNotInGroup: Creator group is private, and specified code is not linked to it
InvalidGroup: No creator group was found with the specified groupId
InvalidAuthCode: AuthCode provided is not valid
ExpiredAuthCode: AuchCode provided has expired
ReferralNexusNotFound: No Nexus was found to match the provided referral code

string

Allowed values: InvalidGroup CodeNotInGroup InvalidAuthCode ExpiredAuthCode ReferralNexusNotFound UnknownError

message

string

GET

/player/{playerId}

const url = 'https://api.nexus.gg/v1/referrals/player/player_8f2c41d0?groupId=V1StGXR8_Z5jdHi6B1LiO&page=1&pageSize=100&excludeReferralList=false';
const options = {method: 'GET', headers: {'X-SHARED-SECRET': 'nexus_pk_your_key_here'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.nexus.gg/v1/referrals/player/player_8f2c41d0?groupId=V1StGXR8_Z5jdHi6B1LiO&page=1&pageSize=100&excludeReferralList=false' \
  --header 'X-SHARED-SECRET: nexus_pk_your_key_here'

Example

{
  "groupId": "V1StGXR8_Z5jdHi6B1LiO",
  "groupName": "Aurora Drift Creators",
  "referralCodes": [
    {
      "code": "popcornfrog",
      "isPrimary": true,
      "isGenerated": false,
      "isManaged": false
    }
  ],
  "playerId": "player_8f2c41d0",
  "currentPage": 1,
  "currentPageSize": 100,
  "totalCount": 15,
  "referrals": [
    {
      "id": "2ixlNNFdJh-9scoXek80w",
      "code": "popcornfrog",
      "playerId": "player_8f2c41d0",
      "playerName": "shadowstrike99",
      "referralDate": "2026-03-13T17:32:28Z"
    }
  ]
}

Example

{
  "code": "InvalidGroup",
  "message": "Invalid Group ID"
}