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

# Validate Referral Code

> Validate a referral code entered by a user during registration

GET [https://api.baanx.com/v1/referral/\{code}/validate](https://api.baanx.com/v1/referral/\{code}/validate)
Validates a referral code when a user enters it, checking whether it is valid or has expired.

## Overview

Use this endpoint during the registration flow to verify a referral code before accepting it. Returns a boolean indicating whether the code is currently valid.

<Note>
  This endpoint only requires the client key — no user Bearer token is needed, as it is intended for use during registration before a user account exists.
</Note>

## Authentication

This endpoint requires only a client key:

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

## Request

### Headers

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

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

### Path Parameters

<ParamField path="code" type="string" required>
  The referral code to validate (e.g., `FHLSO5`)
</ParamField>

### Request Example

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

  ```javascript JavaScript theme={null} theme={null}
  const code = 'FHLSO5';

  const response = await fetch(`https://api.baanx.com/v1/referral/${code}/validate`, {
    method: 'GET',
    headers: {
      'x-client-key': 'YOUR_CLIENT_KEY'
    }
  });

  const data = await response.json();
  console.log(data.valid); // true or false
  ```

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

  code = "FHLSO5"
  url = f"https://api.baanx.com/v1/referral/{code}/validate"
  headers = {
      "x-client-key": "YOUR_CLIENT_KEY"
  }

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

  ```typescript TypeScript theme={null} theme={null}
  interface ValidateReferralResponse {
    valid: boolean;
  }

  const validateReferralCode = async (code: string): Promise<ValidateReferralResponse> => {
    const response = await fetch(`https://api.baanx.com/v1/referral/${code}/validate`, {
      method: 'GET',
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY'
      }
    });

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

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

## Response

### 200 Success

<ResponseField name="valid" type="boolean">
  `true` if the referral code is valid and can be used. `false` if the code is expired or has reached its usage cap.
</ResponseField>

<ResponseExample>
  ```json 200 - Valid Code theme={null} theme={null}
  {
    "valid": true
  }
  ```

  ```json 200 - Invalid Code theme={null} theme={null}
  {
    "valid": false
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 - Bad Request theme={null} theme={null}
  {
    "message": "Invalid request"
  }
  ```

  ```json 422 - Validation Error theme={null} theme={null}
  {
    "message": "Referral code is required"
  }
  ```

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

## Related Endpoints

* `GET /v1/referral/` - Get the authenticated user's own referral code