Create Allocation

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

Endpoint

POST /api/external/v1/allocations

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

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")

Stakeholder Information

Field	Type	Description
walletAddress	string	Blockchain wallet address for the stakeholder
stakeholder	object	Stakeholder information object
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

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

Example Request

curl -X POST https://app.magna.so/api/external/v1/allocations \
  -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": "[email protected]",
      "xHandle": "johndoe",
      "employeeNumber": "EMP-001"
    },
    "category": "Employee Equity",
    "cancellable": true
  }'

Example Response

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

• 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