Data Lists

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

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 listConstraints:

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 listConstraints:

Maximum 500 characters
Can be empty string

items

array

required

Array of string values for the listConstraints:

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

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)

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

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

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

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 valuesNote: This replaces the entire items array. Include all values you want to keep.

Response

data

object

required

The updated data list object

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

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

Create a data list with your predefined values
Create a custom field of type dropdown or select
Associate the field with the data list ID
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"
}

Authentication

Inventory

Management

Data & Reports

Extensions

Overview

Create Data List

Path Parameters

Body Parameters

Response

Get Data Lists

Path Parameters

Response

Update Data List

Path Parameters

Body Parameters

Response

Delete Data List

Path Parameters

Response

Association with Custom Fields

Example Workflow

Validation Rules

Name Validation

Items Validation

Uniqueness

Use Cases

Standardized Equipment Status

Department Assignment

Dynamic List Updates

Conditional Field Population

Error Responses

Build docs developers (and LLMs) love

Authentication

Inventory

Management

Data & Reports

Extensions

​Overview

​Create Data List

​Path Parameters

​Body Parameters

​Response

​Get Data Lists

​Path Parameters

​Response

​Update Data List

​Path Parameters

​Body Parameters

​Response

​Delete Data List

​Path Parameters

​Response

​Association with Custom Fields

​Example Workflow

​Validation Rules

​Name Validation

​Items Validation

​Uniqueness

​Use Cases

​Standardized Equipment Status

​Department Assignment

​Dynamic List Updates

​Conditional Field Population

​Error Responses

Build docs developers (and LLMs) love

Overview

Create Data List

Path Parameters

Body Parameters

Response

Get Data Lists

Path Parameters

Response

Update Data List

Path Parameters

Body Parameters

Response

Delete Data List

Path Parameters

Response

Association with Custom Fields

Example Workflow

Validation Rules

Name Validation

Items Validation

Uniqueness

Use Cases

Standardized Equipment Status

Department Assignment

Dynamic List Updates

Conditional Field Population

Error Responses