> ## 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/:characterId/cancel

> Cancel a pending_approval character submission and return it to draft status. Allows the owner to make edits before resubmitting for staff review.

Use this endpoint to cancel a pending character submission and return the character to `draft` status. This is useful when you have already submitted a character for review but need to make further changes before staff complete their review. Once cancelled, the character's `idStatus` returns to `draft` and you can edit it again using the [Update Character](/api-reference/characters/update-character) endpoint.

<Warning>
  You cannot cancel a character that has already been **approved**. Attempting to do so will return a `403` error. Approved characters are considered finalised and their status cannot be reversed through this endpoint.
</Warning>

<Note>
  If the character is already in `draft` status when you call this endpoint, the server will return `304 Not Modified` with the unchanged character object — no state transition occurs.
</Note>

## Endpoint

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

## Path Parameters

<ParamField path="userId" type="string" required>
  The Snowflake ID of the user who owns the character. Must match the authenticated user's ID.
</ParamField>

<ParamField path="characterId" type="string" required>
  The Snowflake ID of the character whose submission you want to cancel.
</ParamField>

## Query Parameters

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

## Request Body

This endpoint does not require a request body.

## Response

Returns `201 Created` with the updated character object reflecting the restored `draft` status.

If the character was already in `draft` status, returns `304 Not Modified` with the unchanged character object.

<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.
</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">
  The character's restored status. Will be `draft` after a successful cancellation.
</ResponseField>

<ResponseField name="avatarHash" type="string | null">
  Hash identifier for the character's avatar image.
</ResponseField>

<ResponseField name="idCardHash" type="string | null">
  Hash identifier for the character's ID card image.
</ResponseField>

<ResponseField name="fullBodyHash" type="string | null">
  Hash identifier for the character's full-body image.
</ResponseField>

<ResponseField name="avatar3dHash" type="string | null">
  Hash identifier for the character's 3D GLB model.
</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">
  Bounding box metadata for the 3D avatar, or `null` if not set.
</ResponseField>

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

<ResponseField name="signatureData" type="string">
  The character's 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>

## Example Request

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

## 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": "abc123def456",
  "idCardHash": null,
  "fullBodyHash": "fgh789ijk012",
  "avatar3dHash": null,
  "avatar3dCamera": null,
  "avatar3dAABB": null,
  "idStatus": "draft",
  "wallet": null,
  "createdAt": "2024-01-10T14:30:00.000Z",
  "updatedAt": "2024-06-15T13:00: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.                                           |
| `403`  | `Unauthorized`           | The character has already been approved and cannot be cancelled.                                          |
| `304`  | *(no error)*             | The character was already in `draft` status — no change was made. The character object is returned as-is. |
| `404`  | `Unknown User`           | No user was found with the given `userId`.                                                                |
| `404`  | `Unknown Character`      | No character was found with the given `characterId` belonging to this user.                               |
| `500`  | `Missing character data` | An internal error occurred while attempting to update the character's status.                             |