# Managing referrals

Create, retrieve, and delete referrals, and look up the referral code a player is using.

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:

<ApiMethod method="POST" path="/" />
<LinkCard title="View full reference" description="Parameters, responses, and status codes." href="/api/referrals/operations/createreferral/" />

```bash
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:

```json
{
  "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

<Aside type="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](/creator-code-api/program-management/adding-codes-to-your-program/#linking-to-an-existing-nexus)
</Aside>

This response would look something like:

```json
{
  "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:

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

<Aside type="caution">
Because a player may only use a single referral code, each player has one current referral code to retrieve.
</Aside>

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

<ApiMethod method="GET" path="/player/{playerId}/code" />
<LinkCard title="View full reference" description="Parameters, responses, and status codes." href="/api/referrals/operations/getplayercurrentreferral/" />

```bash
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.

```json
"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:

```json
{
  "code": "PlayerHasNoReferral"
}
```

## Retrieve referrals

Retrieve referrals for a Creator Group with this route:

<ApiMethod method="GET" path="/" />
<LinkCard title="View full reference" description="Parameters, responses, and status codes." href="/api/referrals/operations/getallreferrals/" />

```bash
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:

```json
{
  "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

<ApiMethod method="DELETE" path="/{referralId}" />
<LinkCard title="View full reference" description="Parameters, responses, and status codes." href="/api/referrals/operations/eventdelete/" />

```bash
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.

<Aside type="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.
</Aside>

## Next steps

<LinkCard title="Generating codes for your program" description="Link an existing Nexus to your Referral Program." href="/creator-code-api/program-management/adding-codes-to-your-program/" />