Managing referrals

This guide covers creating, retrieving, and deleting referrals for a Creator Group. Referral calls use your private API key, except the player-code lookup, which uses your public API key.

Create a referral

Create a referral with this route:

POST/

View full referenceParameters, responses, and status codes.

curl -X 'POST' \
  'https://api.nexus.gg/v1/referrals' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  -d '{
  "playerId": "playerUniqueIdentifier1",
  "playerName": "dustywusty",
  "code": "abcd123"
}'

The status should be 200 OK with a JSON response body that looks something like this:

{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "referral": {
    "id": "2ixlNNFdJh-9scoXek80w",
    "code": "abcd123",
    "playerId": "playerUniqueIdentifier1",
    "playerName": "dustywusty",
    "referralDate": "2022-09-29T21:30:25.400Z"
  }
}

Private referral programs

Note

If your Referral Program is set to Private, you receive a 400 Bad Request response when using a referral code that does not meet one of the following requirements:

• The Nexus account associated with the referral code is a member of the Creator Group the referral is originating from
• The referral code was generated by you
• The Nexus account associated with the referral code was linked to your Referral Program using the Link Nexus API

This response would look something like:

{
  "code": "CodeNotInGroup",
  "message": "Referral code abcd123 is not linked to creator group CsRKC8uD0NLtyQ0LOt8Ru and is not a group member."
}

Get the current referral code used by a player

A player may only use a single referral code. Attempting to create a referral for a playerId that has already used a code results in an error:

{
  "code": "PlayerAlreadyReferred",
  "message": "Player has already been referred by another nexus."
}

Caution

Because a player may only use a single referral code, each player has one current referral code to retrieve.

Retrieve the current referral code for a player with this route:

GET/player/{playerId}/code

View full referenceParameters, responses, and status codes.

curl -X 'GET' \
  'https://api.nexus.gg/v1/referrals/player/playerUniqueIdentifier1/code' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_pk_your_key_here'

Response status should be 200 with the response body being a string that represents the code current in use.

"abcd123"

If the player has not previously used a referral code, the response status will be 404 Not Found with the following error response body:

{
  "code": "PlayerHasNoReferral"
}

Retrieve referrals

Retrieve referrals for a Creator Group with this route:

GET/

View full referenceParameters, responses, and status codes.

curl -X 'GET' \
  'https://api.nexus.gg/v1/referrals' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here'

The status should be 200 OK with a JSON response body that looks something like this:

{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "currentPage": 1,
  "currentPageSize": 100,
  "totalCount": 1,
  "referrals": [
    {
      "id": "2ixlNNFdJh-9scoXek80w",
      "code": "abcd123",
      "playerId": "playerUniqueIdentifier1",
      "playerName": "dustywusty",
      "referralDate": "2022-09-29T21:30:25.400Z",
      "userId": "userUniqueIdentifier1"
    }
  ]
}

Delete referral

DELETE/{referralId}

View full referenceParameters, responses, and status codes.

curl -X 'DELETE' \
  'https://api.nexus.gg/v1/referrals/2ixlNNFdJh-9scoXek80w' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here'

The response is 200 OK, or 404 Not Found if the referral does not exist.

Caution

If the referral being deleted was counted toward progress of a Bounty Objective, the progress will only be removed if the Bounty has not yet been completed.

Next steps

Generating codes for your programLink an existing Nexus to your Referral Program.