> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magna.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

```json theme={null}
{
  "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