# Create referral

`POST https://api.nexus.gg/v1/referrals/`

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` (string, header, required) - Send your **secret** API key (`nexus_sk_...`) in the `X-SHARED-SECRET` header. [Generate one](/authentication/api-keys/) in the Publisher Dashboard.

## Query parameters

- `groupId` (string) - 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`)

- `code` (string, 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.
- `playerId` (string) - Unique player id. Not visible to Nexus owner
- `playerName` (string) - Display name of player. Visible to Nexus owner

## Responses

### 200

Referral that was created

#### Body (`application/json`)

- `groupId` (string) - ID of the creator group
- `groupName` (string) - Name of the creator group
- `referral` (object)

### 400

bad request

#### Body (`application/json`)

- `code` (string) - CodeNotInGroup: Creator group is private, and specified code is not linked to it<br /> InvalidGroup: No creator group was found with the specified groupId<br/> InvalidAuthCode: AuthCode provided is not valid<br/> ExpiredAuthCode: AuchCode provided has expired<br/> ReferralNexusNotFound: No Nexus was found to match the provided referral code Allowed values: InvalidGroup, CodeNotInGroup, InvalidAuthCode, ExpiredAuthCode, ReferralNexusNotFound, UnknownError.
- `message` (string)