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

# Create Allocation

Create a new allocation for a stakeholder with customizable vesting and unlock schedules.

### Endpoint

```
POST /api/external/v1/allocations/create
```

### Headers

| Header              | Required | Description                |
| ------------------- | -------- | -------------------------- |
| `Content-Type`      | Yes      | Must be `application/json` |
| `x-magna-api-token` | Yes      | Your Magna API token       |

### Request Body

#### Required Fields

| Field         | Type             | Description                                            |
| ------------- | ---------------- | ------------------------------------------------------ |
| `amount`      | string (decimal) | The allocation amount (must be positive)               |
| `contractId`  | string (uuid)    | UUID of the contract to associate with this allocation |
| `tokenId`     | string (uuid)    | UUID of the token for this allocation                  |
| `category`    | string           | Category name for organizing allocations               |
| `stakeholder` | object           | stakeholder information object                         |

**Stakeholder Information**

| Field                        | Type           | Description                            |
| ---------------------------- | -------------- | -------------------------------------- |
| `stakeholder.name`           | string         | Full name of the stakeholder           |
| `stakeholder.email`          | string (email) | Valid email address of the stakeholder |
| `stakeholder.xHandle`        | string         | X (Twitter) handle of the stakeholder  |
| `stakeholder.employeeNumber` | string         | Employee number or ID                  |

#### Optional Fields

**Basic Information**

| Field         | Type           | Description                   |
| ------------- | -------------- | ----------------------------- |
| `description` | string \| null | Description of the allocation |

**Vesting & Unlock Schedules**

| Field               | Type              | Description                                             |
| ------------------- | ----------------- | ------------------------------------------------------- |
| `unlockScheduleId`  | string (uuid)     | UUID of the unlock schedule to apply                    |
| `unlockStartAt`     | string (ISO date) | When the unlock period should start                     |
| `vestingScheduleId` | string (uuid)     | UUID of the vesting schedule to apply                   |
| `vestingStartAt`    | string (ISO date) | When the vesting period should start                    |
| `releaseMode`       | string (enum)     | How tokens should be released (e.g., "LINEAR", "CLIFF") |

**Additional Features**

| Field                      | Type             | Description                                                                          |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `receivedOffMagna`         | string (decimal) | Amount already received outside of Magna (must be positive)                          |
| `cancellable`              | boolean          | Whether the allocation can be cancelled (defaults to `true`)                         |
| `customAttributes`         | array            | Array of custom key-value pairs for additional metadata                              |
| `customAttributes[].key`   | string           | The attribute key                                                                    |
| `customAttributes[].value` | string           | The attribute value                                                                  |
| `walletAddress`            | string           | Recipient's wallet address (will be associated with the token's blockchain platform) |

### Example Request

```bash theme={null}
curl -X POST https://app.magna.so/api/external/v1/allocations/create \
  -H 'Content-Type: application/json' \
  -H 'x-magna-api-token: your_magna_project_api_token' \
  -d '{
    "amount": 50000,
    "description": "Employee equity allocation",
    "contractId": "5b0ff445-b293-40d3-81fa-3a753e4259c4",
    "tokenId": "054d0c03-d20e-477e-81c0-9c2e4453d4a6",
    "unlockScheduleId": "6ef4a3b5-eaa7-4158-9dea-557d4715a72c",
    "unlockStartAt": "2024-04-15T00:00:00.000Z",
    "walletAddress": "0x01f9632EA55Aa14eD6B39aA8EbCEcE425f7ef0e9",
    "stakeholder": {
      "name": "John Doe",
      "email": "john.doe@company.com",
      "xHandle": "johndoe",
      "employeeNumber": "EMP-001"
    },
    "category": "Employee Equity",
    "cancellable": true
  }'
```

### Example Response

```json theme={null}
{
  "isProcessed": true,
  "result": {
    "id": "becf2391-0b8b-4bdf-ae4a-fb6c0d103554",
    "key": "A-DC574CI5YB",
    "amount": "50000",
    "receivedOffMagna": null,
    "funded": null,
    "received": "0",
    "state": "NOT_STARTED",
    "status": "NOT_STARTED",
    "isWalletSubmitted": null,
    "releaseMode": null,
    "description": "Employee equity allocation",
    "releasable": "0",
    "claimable": null,
    "pendingRelease": null,
    "vaultId": null,
    "grantId": null,
    "custodyType": "CONTRACT",
    "projectId": "c74e6bdb-f496-42c7-aaa7-be184ee64913",
    "tokenId": "054d0c03-d20e-477e-81c0-9c2e4453d4a6",
    "stakeholderId": "38f390cc-6e37-46e4-97c1-8a80ca282519",
    "walletId": "d20b6cc1-76f8-46cb-b196-d7eeb872ebf2",
    "categoryId": "61650035-a002-4367-b470-e4cd04209492",
    "createdAt": "2025-07-30T11:15:24.327Z",
    "updatedAt": "2025-07-30T11:15:24.327Z",
    "cancelledAt": null,
    "scheduledCancelAt": null,
    "unlockScheduleId": "6ef4a3b5-eaa7-4158-9dea-557d4715a72c",
    "unlockStartAt": "2024-04-15T00:00:00.000Z",
    "vestingScheduleId": null,
    "vestingStartAt": null
  }
}
```

### Validation Rules

* `amount` must be a positive decimal number
* `contractId` and `tokenId` must be valid UUIDs
* `stakeholder.email` must be a valid email format if provided
* `unlockScheduleId` and `vestingScheduleId` must be valid UUIDs if provided
* Either `unlockScheduleId` or `vestingScheduleId` must be provided
* `receivedOffMagna` must be a positive decimal if provided
* Dates must be in ISO 8601 format
* The token specified by `tokenId` must belong to the project associated with your API token

### Important Notes

* **Category Creation**: If the specified category doesn't exist, it will be automatically created
* **Stakeholder Creation**: A new stakeholder record will be created with the provided information
* **Wallet Association**: If a wallet address is provided, it will be associated with the blockchain platform of the token
* **Default Values**: `cancellable` defaults to `true` if not specified
* **Custody Type**: All allocations created via API use contract custody type

### Error Responses

* **400 Bad Request**: Invalid request body, missing required fields, or validation errors
* **401 Unauthorized**: Invalid or missing API token, or token doesn't belong to the specified project
* **404 Not Found**: Contract ID, token ID, or schedule IDs don't exist
* **422 Unprocessable Entity**: Validation errors (e.g., invalid email format, negative amounts)
* **413 Payload Too Large**: Request body exceeds 1MB limit