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

# Create Student

> Create a new student in your organization

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication (Admin only)
</ParamField>

## Body Parameters

<ParamField body="password" type="string" required>
  Student's password (will be hashed securely)
</ParamField>

<ParamField body="email" type="string">
  Student's email address
</ParamField>

<ParamField body="first_name" type="string">
  Student's first name
</ParamField>

<ParamField body="last_name" type="string">
  Student's last name
</ParamField>

<ParamField body="username" type="string">
  Student's username (auto-generated if not provided)
</ParamField>

<ParamField body="phone_number" type="string">
  Student's phone number
</ParamField>

## Response

<ResponseField name="id" type="integer">
  Unique identifier for the created student
</ResponseField>

<ResponseField name="username" type="string">
  Student's username (auto-generated in AdjectiveNoun format if not provided)
</ResponseField>

<ResponseField name="email" type="string">
  Student's email address
</ResponseField>

<ResponseField name="phone_number" type="string">
  Student's phone number
</ResponseField>

<ResponseField name="first_name" type="string">
  Student's first name
</ResponseField>

<ResponseField name="last_name" type="string">
  Student's last name
</ResponseField>

<ResponseField name="public_report_id" type="string">
  Auto-generated public UUID for student reports
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 timestamp of when the student was created
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.chessplay.io/api/v1/students/ \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "password": "secure_password_123"
    }'
  ```

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

  headers = {
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
  }

  # Minimum required: just password
  data = {
      "password": "secure_password_123"
  }

  # Optional: add more fields
  # data = {
  #     "password": "secure_password_123",
  #     "email": "student@example.com",
  #     "first_name": "John",
  #     "last_name": "Doe"
  # }

  response = requests.post(
      "https://api.chessplay.io/api/v1/students/",
      headers=headers,
      json=data
  )

  student = response.json()
  print(f"Created student: {student['username']}")
  ```

  ```javascript JavaScript theme={null}
  // Minimum required: just password
  const response = await fetch('https://api.chessplay.io/api/v1/students/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      password: 'secure_password_123'
    })
  });

  const student = await response.json();
  console.log(`Created student: ${student.username}`);
  ```

  ```php PHP theme={null}
  <?php
  // Minimum required: just password
  $data = [
      'password' => 'secure_password_123'
  ];

  $ch = curl_init('https://api.chessplay.io/api/v1/students/');
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Authorization: Bearer YOUR_ACCESS_TOKEN',
      'Content-Type: application/json'
  ]);

  $response = curl_exec($ch);
  $student = json_decode($response);
  echo "Created student: {$student->username}\n";
  curl_close($ch);
  ?>
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": 125,
    "username": "BrainyTuna",
    "email": "student@example.com",
    "phone_number": null,
    "first_name": "John",
    "last_name": "Doe",
    "public_report_id": "def-456-ghi-789",
    "created": "2024-01-17T09:15:00Z"
  }
  ```

  ```json 400 Bad Request - Validation Error theme={null}
  {
    "password": ["This field is required."]
  }
  ```

  ```json 400 Bad Request - Duplicate Username theme={null}
  {
    "username": ["This username is already taken in your organization."]
  }
  ```

  ```json 400 Bad Request - Max Limit Reached theme={null}
  {
    "non_field_errors": [
      "Maximum student limit reached. Please contact support at support@wecodethat.com."
    ]
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "detail": "You do not have permission to perform this action."
  }
  ```
</ResponseExample>

## Auto-Generated Usernames

If you don't provide a username, one will be automatically generated in PascalCase format:

* `FastMalamute`
* `TalentedSnail`
* `BrainyTuna`
* `DiligentAardwolf`

<Tip>
  Only **password** is required. All other fields (email, name, username) are optional and will be auto-generated or left empty.
</Tip>

## With Optional Fields

```bash theme={null}
curl -X POST https://api.chessplay.io/api/v1/students/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "secure_password_123",
    "username": "john_doe_2024",
    "email": "student@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+1234567890"
  }'
```

## Important Notes

<Warning>
  Only **Admin users** can create students. Coach and Student users will receive a 403 Forbidden error.
</Warning>

<Note>
  Each organization has a maximum student limit. If you reach this limit, contact support to increase it.
</Note>

<Info>
  Passwords are securely hashed using industry-standard algorithms. They are never stored in plain text.
</Info>