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

# Managing Character Lifecycle in CA Colombia

> Create, submit, and manage the approval lifecycle of in-game characters. Walk through every state transition from draft creation to active approved character.

Every playable character in CA Colombia moves through a defined set of states before becoming active in the game. You start by creating a draft, fill in the required details, then submit it for staff review. Staff either approve or reject the submission — an approved character becomes active and receives a wallet automatically. This guide covers every step and every API call involved in that journey.

## Status Overview

| Status      | Description                                | Available Actions |
| ----------- | ------------------------------------------ | ----------------- |
| `draft`     | Character is being built, not yet reviewed | Edit, Submit      |
| `submitted` | Awaiting staff review                      | Cancel            |
| `approved`  | Active in-game character                   | None (read-only)  |
| `rejected`  | Submission was declined by staff           | Edit, Re-submit   |

## Creating a Character

Send a `POST` request to `/v1/users/{userId}/characters` to create a new character in `draft` status. You must be authenticated as the user specified in the path — you cannot create characters on behalf of another user.

**Endpoint:** `POST /v1/users/{userId}/characters`

**Request body**

| Field         | Type   | Required | Description                                                    |
| ------------- | ------ | -------- | -------------------------------------------------------------- |
| `firstNames`  | string | ✓        | Given name(s), minimum 2 characters                            |
| `lastNames`   | string | ✓        | Family name(s), minimum 2 characters                           |
| `age`         | number | ✓        | Character's age                                                |
| `height`      | number | ✓        | Height in centimetres                                          |
| `gender`      | string | ✓        | `"Masculino"` or `"Femenino"`                                  |
| `bloodType`   | string | ✓        | One of `O+`, `O-`, `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`        |
| `nationality` | string | ✓        | A valid nationality name from the CA Colombia nationality list |
| `dob`         | string | ✓        | Date of birth — any value coercible to a JavaScript `Date`     |

```json theme={null}
{
  "firstNames": "Carlos Andrés",
  "lastNames": "Rodríguez Pérez",
  "age": 28,
  "height": 175,
  "gender": "Masculino",
  "bloodType": "O+",
  "nationality": "Colombiana",
  "dob": "1996-03-14"
}
```

A successful request returns `201 Created` with the full character object, including the newly assigned `characterId` and an `idStatus` of `"draft"`.

**Error responses**

| Status | Error                               | Cause                                                         |
| ------ | ----------------------------------- | ------------------------------------------------------------- |
| `400`  | `Invalid form of body`              | A required field is missing or fails validation               |
| `403`  | `Forbidden`                         | Authenticated user does not match `userId` in the path        |
| `404`  | `Unknown User`                      | No user exists for the given `userId`                         |
| `409`  | `User Max Character Limit Exceeded` | The user already has the maximum number of allowed characters |

<Note>
  Each user account has a maximum character limit. If you hit a `409`, you must delete an existing character before creating a new one.
</Note>

## Editing the Draft

While a character is in `draft` (or `rejected`) status, you can update any of its fields with a `PATCH` request. All fields are optional — include only the ones you want to change.

**Endpoint:** `PATCH /v1/users/{userId}/characters/{characterId}`

```json theme={null}
{
  "height": 180,
  "bloodType": "A+"
}
```

Once a character is submitted, edits are locked until the submission is cancelled.

## Submitting for Review

When you are ready for staff to review the character, submit it with a `POST` to the submit endpoint. The character's status changes from `draft` to `submitted`.

**Endpoint:** `POST /v1/users/{userId}/characters/{characterId}/submit`

No request body is required. A successful submission returns `201` with the updated character object.

You can also append `?signature=true` to include the character's signature data in the response.

**Error responses**

| Status | Error                                | Cause                                                 |
| ------ | ------------------------------------ | ----------------------------------------------------- |
| `403`  | `Forbidden`                          | Authenticated user does not match `userId`            |
| `404`  | `Unknown User` / `Unknown Character` | Resource not found                                    |
| `409`  | `Duplicate Submission`               | Character is already in `submitted` (or later) status |
| `500`  | `Missing character data`             | Required avatar components are not complete           |

<Warning>
  Once submitted, you can no longer edit the character. If you need to make changes after submitting, cancel the submission first to return it to `draft` status.
</Warning>

## Cancelling a Submission

If a character is in `submitted` status and you need to make further changes, cancel the submission to move it back to `draft`.

**Endpoint:** `POST /v1/users/{userId}/characters/{characterId}/cancel`

No request body is required. On success, the server returns `201` with the character in `draft` status.

**Behaviour by status**

| Current Status | Result                                                  |
| -------------- | ------------------------------------------------------- |
| `draft`        | Returns `304` — already a draft, no change made         |
| `submitted`    | Returns `201` — moved back to `draft`                   |
| `approved`     | Returns `403` — approved characters cannot be cancelled |

## After Approval

When staff approve a character, the character's `idStatus` transitions to `"approved"`. The character is now active in the game.

A **wallet** is automatically created and linked to the character the first time the character's data is fetched after approval. If `wallet` is `null` in the response, make a `GET` request to the character endpoint to trigger wallet creation.

Approved characters are active in the game and cannot be re-submitted or edited through the lifecycle endpoints. To query the character's linked bank accounts, use `GET /v1/users/{userId}/characters/{characterId}/bankAccounts`.

<Tip>
  Subscribe to the `characters:update` WebSocket topic to receive a real-time notification the moment a character's status changes. See the [WebSocket guide](/guides/websocket) for details.
</Tip>