> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get User Referral Code

> Retrieve the referral code for the authenticated user

GET [https://api.baanx.com/v1/referral](https://api.baanx.com/v1/referral)
Retrieves the referral code for the authenticated user. If the user is within an active referral campaign, a code will be created and returned. If no active campaign exists, nothing is returned.

## Overview

Returns the authenticated user's referral code along with the cap (maximum number of referrals allowed) and how many have been used. Codes are only issued when an active referral campaign is running for the tenant.

## Authentication

This endpoint requires both a client key and a Bearer token:

```bash theme={null} theme={null}
x-client-key: YOUR_CLIENT_KEY
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for the authenticated user
</ParamField>

<ParamField header="x-us-env" type="boolean" default={false}>
  Set to `true` to route requests to the US backend environment
</ParamField>

### Request Example

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET https://api.baanx.com/v1/referral/ \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null} theme={null}
  const response = await fetch('https://api.baanx.com/v1/referral/', {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null} theme={null}
  import requests

  url = "https://api.baanx.com/v1/referral/"
  headers = {
      "x-client-key": "YOUR_CLIENT_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```typescript TypeScript theme={null} theme={null}
  interface ReferralCode {
    code: string;
    cap: number;
    used: number;
  }

  const getReferralCode = async (): Promise<ReferralCode | null> => {
    const response = await fetch('https://api.baanx.com/v1/referral/', {
      method: 'GET',
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  };
  ```
</CodeGroup>

## Response

### 200 Success

Returns the user's referral code details. If no active campaign exists, the response body will be empty.

<ResponseField name="code" type="string">
  The user's unique referral code (e.g., `FHLSO5`)
</ResponseField>

<ResponseField name="cap" type="number">
  Maximum number of successful referrals allowed for this code
</ResponseField>

<ResponseField name="used" type="number">
  Number of times this referral code has been successfully used
</ResponseField>

<ResponseExample>
  ```json 200 - Active Campaign theme={null} theme={null}
  {
    "code": "FHLSO5",
    "cap": 5,
    "used": 0
  }
  ```

  ```json 200 - No Active Campaign theme={null} theme={null}
  {}
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 - Unauthorized theme={null} theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null} theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 500 - Internal Server Error theme={null} theme={null}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Related Endpoints

* `GET /v1/referral/:code/validate` - Validate a referral code entered by a user during registration