> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autocalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Transfer balance

> Transfer minutes or credits to/from a platform user

This endpoint allows white label admins to transfer call minutes or chat credits to and from their users. This is useful for managing user balances programmatically when building custom frontends.

<Note>
  This endpoint is only available for **white label admins**. Regular users will receive a 403 Forbidden error.
</Note>

### Request Body

<ParamField body="user_id" type="integer">
  The ID of the user to transfer to/from. Required if `email` is not provided.
</ParamField>

<ParamField body="email" type="string">
  The email of the user to transfer to/from. Required if `user_id` is not provided.
</ParamField>

<ParamField body="transfer_type" type="string" required>
  The type of balance to transfer: `minutes` or `credits`
</ParamField>

<ParamField body="operation" type="string" required>
  The operation to perform: `add` (transfer to user) or `remove` (transfer from user)
</ParamField>

<ParamField body="amount" type="number" required>
  The amount to transfer. For minutes, this is the number of call minutes. For credits, this is the number of chat credits.
</ParamField>

### Response

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="transfer" type="object">
  Details of the transfer

  <Expandable title="transfer properties">
    <ResponseField name="type" type="string">
      The transfer type: `minutes` or `credits`
    </ResponseField>

    <ResponseField name="operation" type="string">
      The operation: `add` or `remove`
    </ResponseField>

    <ResponseField name="amount" type="number">
      The amount transferred
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="user" type="object">
  The user's updated balance information

  <Expandable title="user properties">
    <ResponseField name="id" type="integer">
      The user's ID
    </ResponseField>

    <ResponseField name="email" type="string">
      The user's email
    </ResponseField>

    <ResponseField name="name" type="string">
      The user's name
    </ResponseField>

    <ResponseField name="minutes_balance" type="number">
      The user's current minutes balance
    </ResponseField>

    <ResponseField name="credits_balance" type="number">
      The user's current chat credits balance
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="your_balance" type="object">
  Your (tenant owner's) updated balance

  <Expandable title="your_balance properties">
    <ResponseField name="minutes" type="number">
      Your current minutes balance
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 Minutes Transfer Success theme={null}
  {
    "message": "Transfer completed successfully.",
    "transfer": {
      "type": "minutes",
      "operation": "add",
      "amount": 100
    },
    "user": {
      "id": 123,
      "email": "user@example.com",
      "name": "John Doe",
      "minutes_balance": 150.5,
      "credits_balance": 0
    },
    "your_balance": {
      "minutes": 850.5
    }
  }
  ```

  ```json 200 Credits Transfer Success theme={null}
  {
    "message": "Transfer completed successfully.",
    "transfer": {
      "type": "credits",
      "operation": "add",
      "amount": 500
    },
    "user": {
      "id": 123,
      "email": "user@example.com",
      "name": "John Doe",
      "minutes_balance": 0,
      "credits_balance": 500
    },
    "your_balance": {
      "minutes": 944.44
    }
  }
  ```

  ```json 400 Insufficient Balance theme={null}
  {
    "error": "Insufficient minutes balance.",
    "available_balance": 50.5
  }
  ```

  ```json 400 User Insufficient Balance theme={null}
  {
    "error": "User has insufficient credits balance.",
    "user_credits_balance": 25
  }
  ```

  ```json 403 Not White Label Admin theme={null}
  {
    "error": "You are not a white label admin."
  }
  ```

  ```json 403 User Not In Platform theme={null}
  {
    "error": "User does not belong to your white label platform."
  }
  ```

  ```json 404 User Not Found theme={null}
  {
    "error": "User not found."
  }
  ```

  ```json 422 Validation Error theme={null}
  {
    "message": "Either user_id or email is required.",
    "errors": {
      "user_id": ["Either user_id or email is required."],
      "email": ["Either user_id or email is required."]
    }
  }
  ```
</ResponseExample>

### Transfer Types

| Type      | Description                             | Conversion           |
| --------- | --------------------------------------- | -------------------- |
| `minutes` | Call minutes for AI phone calls         | Direct 1:1 transfer  |
| `credits` | Chat credits for AI chat, WhatsApp, SMS | 9 credits = 1 minute |

### Operations

| Operation | Minutes Behavior                        | Credits Behavior                                                  |
| --------- | --------------------------------------- | ----------------------------------------------------------------- |
| `add`     | Deducts from your balance, adds to user | Deducts minutes from you (at 9 credits/min), adds credits to user |
| `remove`  | Deducts from user, adds to your balance | Deducts credits from user, adds minutes to you                    |

### Example: Adding Credits to a User

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "transfer_type": "credits",
    "operation": "add",
    "amount": 100
  }'
```

### Example: Removing Minutes from a User

```bash theme={null}
curl -X POST https://app.autocalls.ai/api/white-label/transfer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 123,
    "transfer_type": "minutes",
    "operation": "remove",
    "amount": 50
  }'
```