# Private referral program

Generate or link a referral code, then create a referral for a private referral program.

A Private Referral Program requires a referral code linked to the program. This could be the Support-a-Creator code for one of the group's members, but this example walks through generating a referral code and linking an existing Nexus account to the program.

<Aside type="note">
Most of the referral API routes accept a `groupId` query parameter, which you may use to specify which Creator Group the operation will occur upon. If this is not provided, your default Creator Group will be used.

For example, `https://api.nexus.gg/v1/referrals?groupId=a30sdfj-20adf-l49ezi`
</Aside>

## Generate a referral code

To generate a referral code, use the following API route:

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

Here's how you call that with `curl`:

```bash
curl -X 'POST' \
  'https://api.nexus.gg/v1/manage/members' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  -d '{
  "playerId": "abcd-123-efg"
}'
```

The only information needed is a `playerId`, which should be a unique identifier for the user in your system that this code will represent. You will be able to retrieve the code by the `playerId`, so there is no need to store any information on your side.

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

```json
{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "playerId": "abcd-123-efg",
  "code": "8ris29f"
}
```

## Link your user to an existing Nexus account

You may also link with an existing Nexus account by having the Nexus owner provide an authentication code that they can generate through the [Nexus Dashboard](https://www.nexus.gg/dashboard/settings).

![An authentication code shown in the Nexus Creator Dashboard with a copy button and an expiration time.](../../../../../../assets/docs/additional-features/referrals/examples/creating-your-first-referral/private-referral-program/creator-dashboard-authentication-code.webp)

Once you have their authentication code, use this route to link the Nexus account associated with the authentication code to a user:

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

Here's how you call that with `curl`:

```bash
curl -X 'POST' \
  'https://api.nexus.gg/v1/manage/members/link' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  -d '{
  "playerId": "abcd-123-efg",
  "authCode": "028-311"
}'
```

Include the authentication code the user provided and, just like when generating a code, a `playerId`, which should be a unique identifier for the user in your system. In this case as well, you will be able to retrieve the code by the `playerId`, so there is no need to store any information on your side.

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

```json
{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "playerId": "abcd-123-efg",
  "codes": [
    {
      "code": "samzorz",
      "isPrimary": true,
      "isGenerated": false,
      "isManaged": false
    },
    {
      "code": "8ris29f",
      "isPrimary": false,
      "isGenerated": true,
      "isManaged": false
    }
  ]
}
```

This example links a Nexus account to the same `playerId` that you generated a code for in the previous section. As a result, the user now has two referral codes associated with it. The code flagged as `isPrimary` will be the one associated with the linked Nexus account. The code generated before will be flagged as `isGenerated`, but it will not be flagged as `isManaged` because it is now managed by the Nexus account it was linked with.

## Create a referral

Now that a referral code is associated with the program, create a referral by making an HTTP POST request to the following route, using your private key for authentication:

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

Here's how you call that with `curl`:

<Aside type="note">
Codes "8ris29f" and "samzorz" will both work in this example and would be associated with the same user.
</Aside>

```bash
curl -X 'POST' \
  'https://api.nexus.gg/v1/referrals' \
  -H 'accept: application/json' \
  -H 'X-SHARED-SECRET: nexus_sk_your_key_here' \
  -d '{
  "code": "8ris29f",
  "playerId": "dlad04-fr9k",
  "playerName": "Test Player"
}'
```

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

```json
{
  "groupId": "CsRKC8uD0NLtyQ0LOt8Ru",
  "groupName": "Test Group",
  "referral": {
    "id": "kFpZIMecDEw0M95Kat3Qr",
    "code": "samzorz",
    "playerId": "dlad04-fr9k",
    "playerName": "Test Player",
    "referralDate": "2022-09-29T21:30:25.400Z"
  }
}
```

## Next steps

You have created a referral in a private referral program. To list, retrieve, or otherwise work with referrals, see managing referrals.

<LinkCard title="Managing referrals" description="List, retrieve, and manage your referrals." href="/additional-features/referrals/managing-referrals/" />