# 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
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
{
  "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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.magna.so/magna-api-documentation/allocations/create-allocation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.