Modify Allocation

Update an existing allocation's properties including wallet address, portal visibility, and custom attributes.

Endpoint

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

Headers

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

Path Parameters

Parameter	Required	Type	Description
allocation_id	Yes	string	The unique identifier of the allocation to modify

Request Body

Field	Required	Type	Description
hideAllocationFromPortal	No	boolean	Controls whether the allocation is visible in the stakeholder portal
walletAddress	No	string	Wallet address for the allocation. Can only be modified for allocations with NOT_STARTED state
customAttributes	No	array	Array of custom key-value pairs for additional allocation metadata
customAttributes[].key	Yes*	string	The attribute key (*required if customAttributes is provided)
customAttributes[].value	Yes*	string	The 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