# Public referral program

Create a referral with a single POST when your Creator Group runs a public referral program.

A public referral program accepts any referral code or Support-a-Creator code, so no setup is required. To create a referral, send a POST request to the following route, authenticating with your private API key.

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

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

ie: https://api.nexus.gg/v1/attributions/referrals?groupId=a30sdfj-20adf-l49ezi
</Aside>

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

```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": "samzorz",
  "playerId": "dlad04-fr9k",
  "playerName": "Test Player"
}'
```

The `code` may be any valid Support-a-Creator code or referral code. The `playerId` and `playerName` properties are both optional and are used to identify the player making the referral. The `playerId` is a unique identifier intended to map the referral to the player in your system and is never displayed to the creator. The `playerName` is a display name for the player and is shown to the creator.

The status should be `200 OK` 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"
  }
}
```

If the code used is not valid, you will receive a `400 Bad Request` response with the following JSON response body:

```json
{
  "code": "ReferralNexusNotFound",
  "message": "No nexus found with code: samzorz."
}
```

## Next steps

<LinkCard title="Private referral program" description="Create a referral when your program only accepts your own group's codes." href="/additional-features/referrals/examples/creating-your-first-referral/private-referral-program/" />