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

# GET /v1/users/:userId/characters — List Characters

> List all in-game characters belonging to a CA Colombia user. Returns an array of character objects with status and biographical data.

Use this endpoint to retrieve all in-game characters that belong to a specific CA Colombia user. The response includes every character regardless of their current approval status, so you will see characters in `draft`, `pending_approval`, and `approved` states all in one call. You can optionally include avatar signature data for each character by passing the `signature` query parameter.

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

## Endpoint

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

## Path Parameters

<ParamField path="userId" type="string" required>
  The Snowflake ID of the user whose characters you want to list. Must match the authenticated user's ID.
</ParamField>

## Query Parameters

<ParamField query="signature" type="string">
  Pass `true` to include each character's `signatureData` field in the response. Omit or pass any other value to exclude it.
</ParamField>

## Response

<ResponseField name="characters" type="array">
  An array of character objects belonging to the user. The array will be empty if the user has no characters.

  <Expandable title="character fields">
    <ResponseField name="characterId" type="string">
      The 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. One of `O+`, `O-`, `A+`, `A-`, `B+`, `B-`, `AB+`, `AB-`.
    </ResponseField>

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

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

    <ResponseField name="avatarHash" type="string | null">
      Hash identifier for the character's avatar image, or `null` if not yet uploaded.
    </ResponseField>

    <ResponseField name="idCardHash" type="string | null">
      Hash identifier for the character's generated ID card image, or `null` if not yet created.
    </ResponseField>

    <ResponseField name="fullBodyHash" type="string | null">
      Hash identifier for the character's full-body reference image, or `null` if not yet uploaded.
    </ResponseField>

    <ResponseField name="avatar3dHash" type="string | null">
      Hash identifier for the character's 3D GLB avatar model, or `null` if not yet uploaded.
    </ResponseField>

    <ResponseField name="avatar3dCamera" type="object | null">
      Camera metadata for the 3D avatar, or `null` if not set.
    </ResponseField>

    <ResponseField name="avatar3dAABB" type="object | null">
      Axis-aligned bounding box metadata for the 3D avatar, or `null` if not set.
    </ResponseField>

    <ResponseField name="idStatus" type="string">
      The character's ID card approval status. One of `draft`, `pending_approval`, or `approved`.
    </ResponseField>

    <ResponseField name="wallet" type="object | null">
      The character's in-game wallet object, or `null` if no wallet exists yet.
    </ResponseField>

    <ResponseField name="signatureData" type="string">
      The character's avatar signature data. Only present when `signature=true` is passed.
    </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>
  </Expandable>
</ResponseField>

## Example Request

```bash theme={null}
curl -X GET "https://api.cacolombia.com/v1/users/112233445566778899/characters" \
  -H "Authorization: Bearer <your_token>"
```

## Example Response

```json theme={null}
{
  "characters": [
    {
      "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": "abc123def456",
      "idCardHash": "xyz789uvw012",
      "fullBodyHash": null,
      "avatar3dHash": null,
      "avatar3dCamera": null,
      "avatar3dAABB": null,
      "idStatus": "approved",
      "wallet": null,
      "createdAt": "2024-01-10T14:30:00.000Z",
      "updatedAt": "2024-06-01T09:15:00.000Z"
    },
    {
      "characterId": "111222333444555666",
      "userId": "112233445566778899",
      "firstNames": "Valentina",
      "lastNames": "Morales López",
      "age": 24,
      "height": 162,
      "gender": "Femenino",
      "bloodType": "A+",
      "nationality": {
        "nombre": "Colombiano",
        "abrev": "COL",
        "lugar": "Colombia"
      },
      "dob": "22/09/2000",
      "avatarHash": null,
      "idCardHash": null,
      "fullBodyHash": null,
      "avatar3dHash": null,
      "avatar3dCamera": null,
      "avatar3dAABB": null,
      "idStatus": "draft",
      "wallet": null,
      "createdAt": "2024-05-20T10:00:00.000Z",
      "updatedAt": "2024-05-20T10:00:00.000Z"
    }
  ]
}
```

## Error Responses

| Status | Error          | Description                                                     |
| ------ | -------------- | --------------------------------------------------------------- |
| `401`  | `Unauthorized` | No valid authentication token was provided.                     |
| `403`  | `Unauthorized` | The authenticated user does not match the `userId` in the path. |
| `404`  | `Unknown User` | No user was found with the given `userId`.                      |