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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.magna.so/magna-api-documentation/allocations/modify-allocation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.