Skip to main content
Create a new allocation for a stakeholder with customizable vesting and unlock schedules.

​
Endpoint

POST /api/external/v1/allocations/create

​
Headers

HeaderRequiredDescription
Content-TypeYesMust be application/json
x-magna-api-tokenYesYour Magna API token

​
Request Body

​
Required Fields

FieldTypeDescription
amountstring (decimal)The allocation amount (must be positive)
contractIdstring (uuid)UUID of the contract to associate with this allocation
tokenIdstring (uuid)UUID of the token for this allocation
categorystringCategory name for organizing allocations
stakeholderobjectstakeholder information object
Stakeholder Information
FieldTypeDescription
stakeholder.namestringFull name of the stakeholder
stakeholder.emailstring (email)Valid email address of the stakeholder
stakeholder.xHandlestringX (Twitter) handle of the stakeholder
stakeholder.employeeNumberstringEmployee number or ID

​
Optional Fields

Basic Information
FieldTypeDescription
descriptionstring | nullDescription of the allocation
Vesting & Unlock Schedules
FieldTypeDescription
unlockScheduleIdstring (uuid)UUID of the unlock schedule to apply
unlockStartAtstring (ISO date)When the unlock period should start
vestingScheduleIdstring (uuid)UUID of the vesting schedule to apply
vestingStartAtstring (ISO date)When the vesting period should start
releaseModestring (enum)How tokens should be released (e.g., “LINEAR”, “CLIFF”)
Additional Features
FieldTypeDescription
receivedOffMagnastring (decimal)Amount already received outside of Magna (must be positive)
cancellablebooleanWhether the allocation can be cancelled (defaults to true)
customAttributesarrayArray of custom key-value pairs for additional metadata
customAttributes[].keystringThe attribute key
customAttributes[].valuestringThe attribute value
walletAddressstringRecipient’s wallet address (will be associated with the token’s blockchain platform)

​
Example Request

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": "[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
  • 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