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

# Characters: In-Game Personas in CA Colombia

> Characters are in-game personas with biographic data, a generated ID card, and a lifecycle from draft to approved. Learn about character fields and statuses.

A **character** is your in-game persona within CA Colombia — the identity you carry inside the roleplay world. Each character has biographic information (name, age, nationality, and more), a generated digital ID card, and a wallet that tracks your in-game finances. Characters go through a review process before they become active in the game, ensuring all personas meet the platform's standards.

## Character Fields

Every character object returned by the API includes the following fields:

| Field          | Type                 | Description                                            |
| -------------- | -------------------- | ------------------------------------------------------ |
| `characterId`  | `string` (Snowflake) | Unique identifier for this character                   |
| `userId`       | `string` (Snowflake) | The user account this character belongs to             |
| `firstNames`   | `string`             | Character's first name(s)                              |
| `lastNames`    | `string`             | Character's last name(s)                               |
| `age`          | `number`             | Age of the character (0–100)                           |
| `height`       | `number`             | Height in centimeters (0–255)                          |
| `gender`       | `string`             | `"Masculino"` or `"Femenino"`                          |
| `bloodType`    | `string`             | One of the eight ABO/Rh blood types                    |
| `nationality`  | `object`             | Nationality object with `nombre`, `abrev`, and `lugar` |
| `dob`          | `string`             | Date of birth in `DD/MM/YYYY` format                   |
| `idStatus`     | `string`             | Current review status (see lifecycle below)            |
| `avatarHash`   | `string \| null`     | Hash of the character's uploaded avatar image          |
| `idCardHash`   | `string \| null`     | Hash of the generated ID card image                    |
| `fullBodyHash` | `string \| null`     | Hash of the full-body image                            |
| `avatar3dHash` | `string \| null`     | Hash of the 3D avatar render                           |
| `wallet`       | `object \| null`     | Wallet data, present only when character is approved   |
| `createdAt`    | `string` (ISO 8601)  | When the character was first created                   |
| `updatedAt`    | `string` (ISO 8601)  | When the character was last modified                   |

### Gender Values

The `gender` field accepts exactly two values:

| Value       | Meaning |
| ----------- | ------- |
| `Masculino` | Male    |
| `Femenino`  | Female  |

### Blood Type Values

The `bloodType` field accepts standard ABO/Rh blood group notation:

`O+` · `O-` · `A+` · `A-` · `B+` · `B-` · `AB+` · `AB-`

### Nationality

The `nationality` field is stored as a nationality name string (`nombre`) and resolved to a full object when returned from the API:

```json theme={null}
{
  "nombre": "Colombiano",
  "abrev": "COL",
  "lugar": "Colombia"
}
```

* **`nombre`** — the nationality adjective (e.g. `"Colombiano"`, `"Estadounidense"`, `"Español"`)
* **`abrev`** — three-letter ISO 3166-1 alpha-3 country code (e.g. `"COL"`, `"USA"`, `"ESP"`)
* **`lugar`** — the country name (e.g. `"Colombia"`, `"Estados Unidos"`, `"España"`)

The platform supports nationalities for all recognized countries worldwide. When creating or updating a character, provide the `nombre` string exactly as it appears in the nationalities list.

***

## ID Status Lifecycle

Every character moves through a review workflow before it can be used in-game. The `idStatus` field reflects the character's current position in that workflow.

```
draft  ──────────►  pending_approval  ──────────►  approved
  ▲                        │
  │                        │ (staff rejects → back to draft)
  └────────────────────────┘
```

<Steps>
  <Step title="draft">
    The character has been created but not yet submitted for review. You can freely edit all fields while a character is in `draft` status. This is the only status where edits are permitted.
  </Step>

  <Step title="pending_approval">
    You have submitted the character for staff review by calling `POST /v1/users/{userId}/characters/{characterId}/submit`. The character is now locked — no edits are allowed while it awaits a decision. You may cancel the submission to return it to `draft` if needed.
  </Step>

  <Step title="approved">
    Staff have approved the character. It is now fully active in the game world. A wallet is created on first access, and the character can earn and spend in-game currency. Approved characters cannot be rolled back to `draft` or `pending_approval`.
  </Step>
</Steps>

<Note>
  When staff reject a character, the `idStatus` is reset to `"draft"` — there is no separate `rejected` status. Check the platform's feedback channel or staff communication for the rejection reason before editing and resubmitting.
</Note>

### Status Summary Table

| Status             | Editable? | Wallet Active? | Description                                             |
| ------------------ | --------- | -------------- | ------------------------------------------------------- |
| `draft`            | ✅ Yes     | ❌ No           | Awaiting submission by you                              |
| `pending_approval` | ❌ No      | ❌ No           | Awaiting staff review; can be cancelled back to `draft` |
| `approved`         | ❌ No      | ✅ Yes          | Active in-game persona                                  |

<Warning>
  Attempting to read wallet data or bank accounts for a character that is not `approved` will return a `403` error. Wallet endpoints are only available after approval.
</Warning>

***

## Character Limits

Each user account has a `maxCharacters` limit (typically 1–3, depending on Discord roles). When you have reached your limit, `POST /v1/users/{userId}/characters` will return an error until you have an available slot.

You can check your current usage at any time by comparing the length of the `characters` array against the `maxCharacters` field on your user object.

***

## Roblox Account Requirement

You must have your Roblox account linked as a provider before you can create any characters. If you attempt to create a character without a linked Roblox account, the API returns a `403 Unauthorized` response.

See [Users & Providers](/concepts/users-and-providers) for instructions on linking your Roblox account.

***

## Example Character Object

```json theme={null}
{
  "characterId": "9876543210987654321",
  "userId": "1234567890123456789",
  "firstNames": "Carlos Andrés",
  "lastNames": "Mendoza Ríos",
  "age": 28,
  "height": 175,
  "gender": "Masculino",
  "bloodType": "O+",
  "nationality": {
    "nombre": "Colombiano",
    "abrev": "COL",
    "lugar": "Colombia"
  },
  "dob": "15/03/1996",
  "idStatus": "approved",
  "avatarHash": "abc123def456",
  "idCardHash": "789ghi012jkl",
  "fullBodyHash": null,
  "avatar3dHash": null,
  "wallet": { "...": "wallet object" },
  "createdAt": "2024-03-01T12:00:00.000Z",
  "updatedAt": "2024-03-10T09:15:00.000Z"
}
```