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

# POST /v1/users/:userId/characters — Create Character

> Create a new in-game character for a CA Colombia user. All biographical fields required. Character starts in draft status, ready for avatar and signature uploads.

Use this endpoint to create a new in-game character for a CA Colombia user. You must provide all required biographical fields in the request body. The character is created with an `idStatus` of `draft`, meaning it is not yet visible to staff for review. Once you are satisfied with the character's data and have uploaded the necessary avatar assets, you can submit it for review using the [Submit Character](/api-reference/characters/submit-character) endpoint.

<Note>
  You can only create characters for your own account. The authenticated token must belong to the same `userId` in the path.
</Note>

<Warning>
  If you have already reached your account's `maxCharacters` limit, this request will return a `409` error. Your limit is determined by your Discord membership and server booster status.
</Warning>

## Endpoint

```text theme={null}
POST https://api.cacolombia.com/v1/users/:userId/characters
```

## Path Parameters

<ParamField path="userId" type="string" required>
  The Snowflake ID of the user for whom the character is being created. Must match the authenticated user's ID.
</ParamField>

## Request Body

All fields are required.

<ParamField body="firstNames" type="string" required>
  The character's first name(s). Must be at least 2 characters long.
</ParamField>

<ParamField body="lastNames" type="string" required>
  The character's last name(s). Must be at least 2 characters long.
</ParamField>

<ParamField body="age" type="number" required>
  The character's age in years.
</ParamField>

<ParamField body="height" type="number" required>
  The character's height in centimetres.
</ParamField>

<ParamField body="gender" type="string" required>
  The character's gender. Must be exactly `Masculino` or `Femenino`.
</ParamField>

<ParamField body="bloodType" type="string" required>
  The character's blood type. Must be one of: `O+`, `O-`, `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`.
</ParamField>

<ParamField body="nationality" type="string" required>
  The character's nationality name. Must be a valid nationality from the CA Colombia platform list (e.g. `Colombiano`). Invalid values will be rejected with a `400` error.
</ParamField>

<ParamField body="dob" type="string" required>
  The character's date of birth as an ISO 8601 date string (e.g. `1996-04-15`). The stored value will be formatted as `DD/MM/YYYY`.
</ParamField>

## Response

On success, returns `201 Created` with the newly created character object.

<ResponseField name="characterId" type="string">
  The new character's unique Snowflake ID.
</ResponseField>

<ResponseField name="userId" type="string">
  The Snowflake ID of the user who owns this character.
</ResponseField>

<ResponseField name="firstNames" type="string">
  The character's first name(s).
</ResponseField>

<ResponseField name="lastNames" type="string">
  The character's last name(s).
</ResponseField>

<ResponseField name="age" type="number">
  The character's age in years.
</ResponseField>

<ResponseField name="height" type="number">
  The character's height in centimetres.
</ResponseField>

<ResponseField name="gender" type="string">
  The character's gender. Either `Masculino` or `Femenino`.
</ResponseField>

<ResponseField name="bloodType" type="string">
  The character's blood type.
</ResponseField>

<ResponseField name="nationality" type="object">
  An object describing the character's nationality with `nombre`, `abrev`, and `lugar` fields.
</ResponseField>

<ResponseField name="dob" type="string">
  The character's date of birth in `DD/MM/YYYY` format.
</ResponseField>

<ResponseField name="idStatus" type="string">
  Always `draft` for a newly created character.
</ResponseField>

<ResponseField name="avatarHash" type="null">
  `null` on creation — no avatar has been uploaded yet.
</ResponseField>

<ResponseField name="idCardHash" type="null">
  `null` on creation — no ID card has been generated yet.
</ResponseField>

<ResponseField name="fullBodyHash" type="null">
  `null` on creation — no full-body image has been uploaded yet.
</ResponseField>

<ResponseField name="avatar3dHash" type="null">
  `null` on creation — no 3D avatar has been uploaded yet.
</ResponseField>

<ResponseField name="wallet" type="null">
  `null` on creation — no wallet has been assigned yet.
</ResponseField>

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

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp of when the character was last updated.
</ResponseField>

## Example Request

```bash theme={null}
curl -X POST "https://api.cacolombia.com/v1/users/112233445566778899/characters" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstNames": "Carlos Alberto",
    "lastNames": "Reyes Gómez",
    "age": 28,
    "height": 175,
    "gender": "Masculino",
    "bloodType": "O+",
    "nationality": "Colombiano",
    "dob": "1996-04-15"
  }'
```

## Example Response

```json theme={null}
{
  "characterId": "998877665544332211",
  "userId": "112233445566778899",
  "firstNames": "Carlos Alberto",
  "lastNames": "Reyes Gómez",
  "age": 28,
  "height": 175,
  "gender": "Masculino",
  "bloodType": "O+",
  "nationality": {
    "nombre": "Colombiano",
    "abrev": "COL",
    "lugar": "Colombia"
  },
  "dob": "15/04/1996",
  "avatarHash": null,
  "idCardHash": null,
  "fullBodyHash": null,
  "avatar3dHash": null,
  "avatar3dCamera": null,
  "avatar3dAABB": null,
  "idStatus": "draft",
  "wallet": null,
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}
```

## Error Responses

| Status | Error                               | Description                                                                                                       |
| ------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `401`  | `Unauthorized`                      | No valid authentication token was provided.                                                                       |
| `403`  | `Forbidden`                         | The authenticated user does not match the `userId` in the path.                                                   |
| `404`  | `Unknown User`                      | No user was found with the given `userId`.                                                                        |
| `400`  | `Invalid form of body`              | One or more request body fields failed validation. The response includes a `details` field describing each issue. |
| `409`  | `User Max Character Limit Exceeded` | The user already has the maximum number of allowed characters and cannot create another.                          |