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

POST /containers/{containerId}/datalists

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

Show 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)

Response

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

GET /containers/{containerId}/datalists

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

Response

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

PUT /datalists/{dataListId}

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

Response

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

DELETE /datalists/{dataListId}

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.

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

Example Custom Field Definition

{
  "name": "Equipment Status",
  "type": "dropdown",
  "dataListId": 42,
  "required": true
}

Validation Rules

Name Validation

Valid: “Equipment Status”

Valid: “Priority-Levels_2024”

Items Validation

Valid: [“Option 1”, “Option 2”, “Option 3”]

Valid: [“Single Item”] (minimum 1 item)

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

// 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

// 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

// 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

// 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.

{
  "error": "Validation failed",
  "details": {
    "name": "Name cannot be empty",
    "items": "At least one item is required"
  }
}

401 Unauthorized

Returned when authentication fails.

{
  "error": "No autorizado. Por favor, inicie sesión nuevamente."
}

404 Not Found

Returned when the data list or container is not found.

{
  "error": "Lista personalizada no encontrada."
}

409 Conflict

Returned when a data list with the same name already exists.

{
  "error": "A data list with this name already exists in this container"
}

500 Internal Server Error

Returned when an unexpected error occurs.

{
  "error": "Error inesperado",
  "message": "Database connection failed"
}