> ## 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/banks — Create and Register an In-Game Bank

> Register a new in-game bank owned by an existing character. Requires SERVICE_ADMINISTRATOR permission. Optionally sets the bank's starting capital balance.

Use this endpoint to register a new in-game bank on the CA Colombia platform. Banks are owned by a specific character and hold capital that funds their operations. When you create a bank you can optionally specify a starting capital amount; if omitted, the bank is created with zero capital.

<Warning>
  Creating a bank requires the `SERVICE_ADMINISTRATOR` permission. This is a privileged operation reserved for platform administrators — it is not available to regular users.
</Warning>

## Endpoint

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

## Request Body

<ParamField body="ownerId" type="string" required>
  The `characterId` (Snowflake ID) of the character who will own the new bank. The character must already exist in the system.
</ParamField>

<ParamField body="name" type="string" required>
  The display name for the bank.
</ParamField>

<ParamField body="capital" type="number">
  The initial capital balance for the bank, in in-game currency units. Defaults to `0` if omitted.
</ParamField>

## Response

A successful `201 Created` response returns the newly created bank object:

<ResponseField name="bankId" type="string">
  The unique Snowflake ID for this bank.
</ResponseField>

<ResponseField name="ownerId" type="string">
  The `characterId` of the character who owns the bank.
</ResponseField>

<ResponseField name="name" type="string">
  The display name of the bank.
</ResponseField>

<ResponseField name="iconHash" type="string | null">
  The hash of the bank's icon image, or `null` if no icon has been set. Use this with the [images endpoint](/api-reference/images) to retrieve the icon.
</ResponseField>

<ResponseField name="capital" type="number">
  The bank's current capital balance.
</ResponseField>

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

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

## Example Request

```bash theme={null}
curl -X POST "https://api.cacolombia.com/v1/banks" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerId": "998877665544332211",
    "name": "Banco Nacional",
    "capital": 1000000
  }'
```

## Example Response

```json theme={null}
{
  "bankId": "112233445566778800",
  "ownerId": "998877665544332211",
  "name": "Banco Nacional",
  "iconHash": null,
  "capital": 1000000,
  "createdAt": "2024-06-01T08:00:00.000Z",
  "updatedAt": "2024-06-01T08:00:00.000Z"
}
```

## Error Responses

| Status | Description                                                                            |
| ------ | -------------------------------------------------------------------------------------- |
| `400`  | The request body is missing `ownerId` or `name`, or contains values of the wrong type. |
| `401`  | You are not authenticated. Provide a valid authorization token with your request.      |
| `403`  | Your account does not hold the `SERVICE_ADMINISTRATOR` permission.                     |
| `404`  | No character was found for the given `ownerId`.                                        |