Skip to main content
Update an existing allocation’s properties including wallet address, portal visibility, and custom attributes.

​
Endpoint

POST /api/external/v1/allocations/{allocation_id}/modify

​
Headers

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

​
Path Parameters

ParameterRequiredTypeDescription
allocation_idYesstringThe unique identifier of the allocation to modify

​
Request Body

FieldRequiredTypeDescription
hideAllocationFromPortalNobooleanControls whether the allocation is visible in the stakeholder portal
walletAddressNostringWallet address for the allocation. Can only be modified for allocations with NOT_STARTED state
customAttributesNoarrayArray of custom key-value pairs for additional allocation metadata
customAttributes[].keyYes*stringThe attribute key (*required if customAttributes is provided)
customAttributes[].valueYes*stringThe attribute value (*required if customAttributes is provided)

​
Important Notes

  • Wallet Address Restriction: The walletAddress field can only be modified for allocations that have not yet started (state: NOT_STARTED). Attempting to modify the wallet address for started allocations will result in an error.
  • All fields are optional, allowing you to update only the specific properties you need to change.

​
Example Request

curl -X POST https://app.magna.so/api/external/v1/allocations/7eb179c5-d86a-4c0c-be29-198ad0cb39b0/modify \
  -H 'Content-Type: application/json' \
  -H 'x-magna-api-token: your_magna_project_api_token' \
  -d '{
    "walletAddress": "0x01f9632EA55Aa14eD6B39aA8EbCEcE425f7ef0e9",
    "hideAllocationFromPortal": false,
    "customAttributes": [
      {
        "key": "department",
        "value": "Engineering"
      },
      {
        "key": "employeeLevel",
        "value": "Senior"
      }
    ]
  }'

​
Example Response

{
  "isProcessed": true,
  "result": {
    "id": "7eb179c5-d86a-4c0c-be29-198ad0cb39b0",
    "key": "A-SMJ7LTO1GS",
    "description": null,
    "amount": "12000",
    "funded": "0",
    "received": "0",
    "walletAddress": "0x01f9632EA55Aa14eD6B39aA8EbCEcE425f7ef0e9",
    "createdAt": "2024-04-15T21:26:21.000Z",
    "updatedAt": "2024-04-15T21:26:21.000Z",
    "cancelledAt": null,
    "state": "NOT_STARTED",
    "stakeholder": {
      "id": "fe2d5104-36d5-4c79-b457-6bfcb1ae498c",
      "type": null,
      "employeeNumber": null,
      "name": null,
      "contactEmail": null
    },
    "customAttributes": [
      {
        "key": "department",
        "value": "Engineering"
      },
      {
        "key": "employeeLevel",
        "value": "Senior"
      }
    ],
    "category": {
      "id": "3451cadc-dd25-4aee-b000-453756796a06",
      "name": "Category-Name"
    },
    "unlockStartAt": "2024-04-15T21:26:21.000Z",
    "vestingStartAt": "2024-04-15T21:26:21.000Z"
  }
}

​
Response Fields

The response returns the complete updated allocation object with the following structure:
  • isProcessed: Boolean indicating if the request was successfully processed
  • result: The updated allocation object containing all allocation details including the modifications made

​
Error Responses

  • 400 Bad Request: Invalid request body or attempting to modify wallet address for a started allocation
  • 401 Unauthorized: Invalid or missing API token
  • 404 Not Found: Allocation with the specified ID does not exist
  • 422 Unprocessable Entity: Validation errors in the request body