Modify List Items

Route

/v2/lists/{id}/items/modify

Description

Modify multiple items in a list with bulk operations. This endpoint supports adding, updating, and removing items in a single request.

Method

POST

Inputs

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the list
operations	array[Operation]	Yes	Array of modification operations

Operation Object

Parameter	Type	Required	Description
action	string	Yes	Operation type (add, update, remove)
item_id	string	No	Item ID (required for update/remove)
value	string	No	Item value (required for add/update)
description	string	No	Item description
metadata	object	No	Additional item metadata

Request Body

{
  "operations": [
    {
      "action": "add",
      "value": "new@company.com",
      "description": "New executive email",
      "metadata": {
        "category": "executive",
        "priority": "high"
      }
    },
    {
      "action": "update",
      "item_id": "item-456",
      "value": "updated@company.com",
      "description": "Updated email address",
      "metadata": {
        "category": "executive",
        "priority": "medium"
      }
    },
    {
      "action": "remove",
      "item_id": "item-789"
    }
  ]
}

Output

Field	Type	Description
list_id	string	List identifier
results	array[OperationResult]	Results for each operation
summary	object	Summary of operations performed
errors	array[Error]	Any errors encountered

Operation Result Object

Field	Type	Description
operation_index	integer	Index of operation in request
action	string	Operation type performed
success	boolean	Whether operation succeeded
item_id	string	Item ID (for successful operations)
error	string	Error message (for failed operations)

Summary Object

Field	Type	Description
total_operations	integer	Total number of operations
successful_operations	integer	Number of successful operations
failed_operations	integer	Number of failed operations
items_added	integer	Number of items added
items_updated	integer	Number of items updated
items_removed	integer	Number of items removed

Rate Limit

• 60 requests per minute per API key
• 5 concurrent requests per endpoint

Example Response

{
  "list_id": "list-123",
  "results": [
    {
      "operation_index": 0,
      "action": "add",
      "success": true,
      "item_id": "item-new123"
    },
    {
      "operation_index": 1,
      "action": "update",
      "success": true,
      "item_id": "item-456"
    },
    {
      "operation_index": 2,
      "action": "remove",
      "success": true,
      "item_id": "item-789"
    }
  ],
  "summary": {
    "total_operations": 3,
    "successful_operations": 3,
    "failed_operations": 0,
    "items_added": 1,
    "items_updated": 1,
    "items_removed": 1
  },
  "errors": []
}

Error Response

{
  "list_id": "list-123",
  "results": [
    {
      "operation_index": 0,
      "action": "add",
      "success": false,
      "error": "Duplicate value not allowed"
    }
  ],
  "summary": {
    "total_operations": 1,
    "successful_operations": 0,
    "failed_operations": 1,
    "items_added": 0,
    "items_updated": 0,
    "items_removed": 0
  },
  "errors": []
}