Create referral

Creates a referral, linking a player to the creator whose code they used. The code must resolve to an approved Nexus with an approved membership in your creator group; a code that doesn’t resolve returns 400 with ReferralNexusNotFound. Creating the referral publishes a referral event that a downstream bounty processor uses to advance any bounty with a referral objective.

Authorizations

X-SHARED-SECRET

required

stringheader

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

Parameters

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.

Request Body

application/x-www-form-urlencoded

object

code

required

The creator’s referral code used to look up the Nexus for this referral. Must belong to an approved Nexus with an approved membership in your creator group.

string

Example

popcornfrog

playerId

Unique player id. Not visible to Nexus owner

string

Example

player_8f2c41d0

playerName

Display name of player. Visible to Nexus owner

string

Example

shadowstrike99

Responses

200

Referral that was created

application/json

object

groupId

ID of the creator group

string

groupName

Name of the creator group

string

referral

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

POST

const url = 'https://api.nexus.gg/v1/referrals/?groupId=V1StGXR8_Z5jdHi6B1LiO';
const options = {
  method: 'POST',
  headers: {
    'X-SHARED-SECRET': 'nexus_sk_your_key_here',
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({code: 'popcornfrog', playerId: 'player_8f2c41d0', playerName: 'shadowstrike99'})
};

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

curl --request POST \
  --url 'https://api.nexus.gg/v1/referrals/?groupId=V1StGXR8_Z5jdHi6B1LiO' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  --data code=popcornfrog \
  --data playerId=player_8f2c41d0 \
  --data playerName=shadowstrike99

Example

{
  "groupId": "V1StGXR8_Z5jdHi6B1LiO",
  "groupName": "Aurora Drift Creators",
  "referral": {
    "id": "2ixlNNFdJh-9scoXek80w",
    "code": "popcornfrog",
    "playerId": "player_8f2c41d0",
    "playerName": "shadowstrike99",
    "referralDate": "2026-03-13T17:32:28Z"
  }
}

Example

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