> ## Documentation Index > Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Data Lists > Manage custom data lists for dropdown fields and data validation ## Overview Data lists are reusable collections of predefined values that can be associated with custom fields. They enable: * Consistent data entry across inventory items * Dropdown menus in custom fields * Data validation and standardization * Centralized management of field options **Common Use Cases:** * Status values (New, Used, Refurbished) * Priority levels (Low, Medium, High, Critical) * Departments (IT, Sales, Operations, HR) * Categories or classifications * Vendor or supplier lists ## Create Data List ```bash POST /containers/{containerId}/datalists theme={null} curl -X POST "https://api.invenicum.com/containers/1/datalists" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Equipment Status", "description": "Standard status values for equipment tracking", "items": ["New", "Good", "Fair", "Needs Repair", "Retired"] }' ``` Creates a new data list within a container. ### Path Parameters **containerId** `integer` *required* The unique identifier of the container where the data list will be created ### Body Parameters **name** `string` *required* Name of the data list **Constraints:** * Must be unique within the container * Maximum 100 characters * Cannot be empty or whitespace only **description** `string` *required* Description explaining the purpose of this data list **Constraints:** * Maximum 500 characters * Can be empty string **items** `array` *required* Array of string values for the list **Constraints:** * Must contain at least one item * Maximum 200 items per list * Each item: maximum 100 characters * Duplicate values are allowed but not recommended ### Response **data** `object` *required* The created data list object **ListData Properties** **id** `integer` *required* Unique identifier for the data list **name** `string` *required* Name of the data list **description** `string` Description of the data list **items** `array` *required* Array of string values in the list **created\_at** `string` Timestamp when the list was created (ISO 8601) **updated\_at** `string` Timestamp when the list was last updated (ISO 8601) ```json Response theme={null} { "data": { "id": 42, "name": "Equipment Status", "description": "Standard status values for equipment tracking", "items": [ "New", "Good", "Fair", "Needs Repair", "Retired" ], "created_at": "2024-03-15T10:30:00Z", "updated_at": "2024-03-15T10:30:00Z" } } ``` ## Get Data Lists ```bash GET /containers/{containerId}/datalists theme={null} curl -X GET "https://api.invenicum.com/containers/1/datalists" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` Retrieves all data lists for a specific container. ### Path Parameters **containerId** `integer` *required* The unique identifier of the container ### Response **data** `array` *required* Array of data list objects ```json Response theme={null} { "data": [ { "id": 42, "name": "Equipment Status", "description": "Standard status values for equipment tracking", "items": ["New", "Good", "Fair", "Needs Repair", "Retired"], "created_at": "2024-03-15T10:30:00Z", "updated_at": "2024-03-15T10:30:00Z" }, { "id": 43, "name": "Priority Levels", "description": "Item priority classification", "items": ["Low", "Medium", "High", "Critical"], "created_at": "2024-03-14T14:22:00Z", "updated_at": "2024-03-14T14:22:00Z" }, { "id": 44, "name": "Departments", "description": "Organization departments", "items": ["IT", "Sales", "Operations", "HR", "Finance", "Marketing"], "created_at": "2024-03-10T09:15:00Z", "updated_at": "2024-03-12T16:45:00Z" } ] } ``` ## Update Data List ```bash PUT /datalists/{dataListId} theme={null} curl -X PUT "https://api.invenicum.com/datalists/42" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Equipment Condition", "description": "Updated status values for equipment condition tracking", "items": ["Brand New", "Excellent", "Good", "Fair", "Poor", "Retired"] }' ``` Updates an existing data list. ### Path Parameters **dataListId** `integer` *required* The unique identifier of the data list to update ### Body Parameters **name** `string` *required* Updated name of the data list **description** `string` *required* Updated description **items** `array` *required* Updated array of string values **Note:** This replaces the entire items array. Include all values you want to keep. ### Response **data** `object` *required* The updated data list object ```json Response theme={null} { "data": { "id": 42, "name": "Equipment Condition", "description": "Updated status values for equipment condition tracking", "items": [ "Brand New", "Excellent", "Good", "Fair", "Poor", "Retired" ], "created_at": "2024-03-15T10:30:00Z", "updated_at": "2024-03-15T14:25:00Z" } } ``` ## Delete Data List ```bash DELETE /datalists/{dataListId} theme={null} curl -X DELETE "https://api.invenicum.com/datalists/42" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` Deletes a data list from the system. ### Path Parameters **dataListId** `integer` *required* The unique identifier of the data list to delete ### Response Returns `204 No Content` on successful deletion. > [!WARNING] > > Deleting a data list that is associated with custom fields may affect data validation. Ensure the list is no longer in use before deletion. ## Association with Custom Fields Data lists are typically used with dropdown-type custom fields. When creating a custom field definition, you can associate it with a data list to provide predefined values. ### Example Workflow 1. **Create a data list** with your predefined values 2. **Create a custom field** of type `dropdown` or `select` 3. **Associate the field** with the data list ID 4. **Use in inventory items** - users can only select values from the list ```json Example Custom Field Definition theme={null} { "name": "Equipment Status", "type": "dropdown", "dataListId": 42, "required": true } ``` ## Validation Rules ### Name Validation > [!TIP] > > Valid: "Equipment Status" > [!TIP] > > Valid: "Priority-Levels\_2024" Invalid: "" (empty string)Invalid: " " (whitespace only)Invalid: Names exceeding 100 characters ### Items Validation > [!TIP] > > Valid: \["Option 1", "Option 2", "Option 3"] > [!TIP] > > Valid: \["Single Item"] (minimum 1 item) Invalid: \[] (empty array)Invalid: Arrays with more than 200 itemsInvalid: Items exceeding 100 characters ### Uniqueness Data list names must be unique within each container. Two different containers can have data lists with the same name. ## Use Cases ### Standardized Equipment Status ```javascript theme={null} // Create a status data list const statusList = await fetch('/containers/1/datalists', { method: 'POST', body: JSON.stringify({ name: 'Equipment Status', description: 'Standard equipment condition values', items: ['New', 'Good', 'Fair', 'Needs Repair', 'Retired'] }) }); // Associate with custom field const customField = await createCustomField({ name: 'Condition', type: 'dropdown', dataListId: statusList.data.id }); ``` ### Department Assignment ```javascript theme={null} // Create department list const deptList = await fetch('/containers/1/datalists', { method: 'POST', body: JSON.stringify({ name: 'Departments', description: 'Company departments', items: ['IT', 'Sales', 'Operations', 'HR', 'Finance'] }) }); // Items can now be assigned to specific departments // with guaranteed consistency ``` ### Dynamic List Updates ```javascript theme={null} // Fetch existing list const lists = await fetch('/containers/1/datalists'); const deptList = lists.data.find(l => l.name === 'Departments'); // Add new department const updatedItems = [...deptList.items, 'Marketing']; await fetch(`/datalists/${deptList.id}`, { method: 'PUT', body: JSON.stringify({ name: deptList.name, description: deptList.description, items: updatedItems }) }); ``` ### Conditional Field Population ```javascript theme={null} // Load data lists for a container const lists = await fetch('/containers/1/datalists'); // Populate dropdown based on user selection function populateDropdown(fieldType) { const list = lists.data.find(l => l.name === fieldType); return list ? list.items : []; } // Example: User selects "Status" field type const options = populateDropdown('Equipment Status'); // Returns: ['New', 'Good', 'Fair', 'Needs Repair', 'Retired'] ``` ## Error Responses **400 Bad Request** Returned when validation fails. ```json theme={null} { "error": "Validation failed", "details": { "name": "Name cannot be empty", "items": "At least one item is required" } } ``` **401 Unauthorized** Returned when authentication fails. ```json theme={null} { "error": "No autorizado. Por favor, inicie sesión nuevamente." } ``` **404 Not Found** Returned when the data list or container is not found. ```json theme={null} { "error": "Lista personalizada no encontrada." } ``` **409 Conflict** Returned when a data list with the same name already exists. ```json theme={null} { "error": "A data list with this name already exists in this container" } ``` **500 Internal Server Error** Returned when an unexpected error occurs. ```json theme={null} { "error": "Error inesperado", "message": "Database connection failed" } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.