Custom Fields

Custom fields allow you to extend the InLoox data models with your own attributes. Through the API, you can manage field definitions, read and update values, and control access permissions.

Dynamic Endpoints

To retrieve custom fields together with the standard properties of an entity, use the Dynamic* endpoints (e.g., DynamicProject, DynamicTaskItem, DynamicContact). These return all configured custom fields as additional columns.

To access custom fields, use the Dynamic variants of the entities:

Standard Entity	Dynamic Variant	Description
Project	DynamicProject	Projects with custom fields
Planning	DynamicPlanning	Planning elements with custom fields
Task	DynamicTaskItem	Tasks with custom fields
TimeEntry	DynamicTimeEntry	Time entries with custom fields
Budget	DynamicBudget	Budgets with custom fields
LineItem	DynamicLineItem	Line items with custom fields
n/a	DynamicContact	Contacts with custom fields

---

CustomField

The CustomField entity provides direct access to individual custom field values. Each value is identified by the field name (Name) and the object ID (ObjectId).

Composite Key

CustomField uses a composite key consisting of Name and ObjectId. Two URL notations are supported for accessing individual values: bracket notation and slash notation. Both behave identically.

Data Model

Property	Type	Description
ObjectId	guid	ID of the object the field is assigned to (e.g., ProjectId, TaskItemId).
Name	string	Internal column name of the custom field, e.g., "cf_f52d9d79_Location". See in InLoox under Account Settings > Custom Fields.
Value	string	The value of the custom field.
Type	string	The data type of the field: String, DateTime, Integer, Decimal, Boolean, List, Currency, Range, MultiList, Person.

Endpoints

Retrieve a value (bracket notation)

Retrieve a custom field value

GET/odata/CustomField(Name={keyName},ObjectId={keyObjectId})?tableName={tableName}

Parameter	Type	Required	Description
keyName	string	✅	The internal column name of the field.
keyObjectId	guid	✅	The ID of the associated object.
tableName	string	✅	The base entity table that contains the custom field value (for example `Planning`, `Project`, `TaskItem`). Pass as query parameter: `?tableName=Planning`.

---

Update a value (bracket notation)

Update a custom field value

PATCH/odata/CustomField(Name={keyName},ObjectId={keyObjectId})

Parameter	Type	Required	Description
keyName	string	✅	The internal column name of the field.
keyObjectId	guid	✅	The ID of the associated object.
Body	object	✅	JSON object with the following fields: Value (string, required) — The new value of the custom field.

---

Retrieve a value (slash notation)

Retrieve a custom field value using slash notation

GET/odata/CustomField/Name={keyName},ObjectId={keyObjectId}?tableName={tableName}

Parameter	Type	Required	Description
keyName	string	✅	The internal column name of the field.
keyObjectId	guid	✅	The ID of the associated object.
tableName	string	✅	The base entity table that contains the custom field value (for example `Planning`, `Project`, `TaskItem`). Pass as query parameter: `?tableName=Planning`.

---

Update a value (slash notation)

Update a custom field value using slash notation

PATCH/odata/CustomField/Name={keyName},ObjectId={keyObjectId}

Parameter	Type	Required	Description
keyName	string	✅	The internal column name of the field.
keyObjectId	guid	✅	The ID of the associated object.
Body	object	✅	JSON object with the following fields: Value (string, required) — The new value of the custom field.

---

Batch update

Update multiple custom field values at once

POSTodata/CustomField/BatchUpdate

Parameter	Type	Required	Description
Body	array	✅	JSON array of objects with the following fields per entry: ObjectId (guid, required) — The ID of the entity (e.g., project or task ID). Name (string, required) — The internal column name of the custom field. Value (string?, optional) — The value to set. Pass null to clear the field.

Allows updating multiple custom fields in a single call.

Batch Update

Use BatchUpdate when you want to set multiple custom fields for an object at the same time. This is more efficient than multiple individual PATCH calls.

Person fields

For custom fields of type Person, the Value must be a JSON array of contact IDs (as strings). The API resolves the IDs to the corresponding contact names and profile pictures.

Example: "[\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\"yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\"]" — sets the field to two contacts.

---

CustomFieldDefinition

The CustomFieldDefinition entity describes the metadata of a custom field, including data type, display name, and validation rules.

Data Model

Property	Type	Description
CustomFieldDefinitionId	guid	Unique ID of the field definition.
ColumnName	string	Internal column name (unique identifier).
DisplayName	string	Display name of the field in the user interface.
TableName	string	Table the field is assigned to. Values: TimeEntry (0), LineItem (1), Budget (2), Document (3), MindMapNode (4), MindMap (5), Planning (6), TaskItem (7), Project (8), CheckList (9), FiscalPeriodFunding (10), Risk (11), Contact (12), PresetLineItem (101), Preset (102).
OrdinalPosition	int?	Sort position of the field.
StringValue	string	Default value (string).
IntValue	int?	Default value (integer).
BoolValue	bool	Default value (boolean).
WriteProtectionEnabled	bool	Whether write protection is enabled.
DecimalValue	decimal?	Default value (decimal).
DateTimeValue	DateTimeOffset?	Default value (date/time).
ColumnType	int	Data type of the column. Values: 0 = String (text), 1 = DateTime (date and time), 2 = Integer (whole number), 3 = Decimal (decimal number), 4 = Boolean (yes/no value), 5 = List, 6 = Currency, 7 = Range, 8 = MultiList, 9 = Person.
DisplayRuleField	string	Field name for conditional display.
DisplayRuleExpression	string	Expression for conditional display.
CurrencySymbol	string	Currency symbol (for currency fields).
MinValue	int?	Minimum value (for Range fields).
MaxValue	int?	Maximum value (for Range fields).
AllowMultiplePersons	bool	Whether users may select more than one person (for Person fields).
WarningIfEmpty	bool	Show a warning if the field is empty.
AllowAddNewItem	bool	Whether users may add new values to the dropdown list.
DefaultCustomFieldDefinitionListId	guid?	ID of the default dropdown list.
DefaultCustomFieldDefinitionListValue	string	Default value from the dropdown list.
CustomFieldSectionId	guid	ID of the section this field belongs to. See CustomFieldSection.

Endpoints

Retrieve all field definitions for the entire account

GET/odata/CustomFieldDefinition

Supports OData query options.

---

Retrieve a field definition by ID

GET/odata/CustomFieldDefinition({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldDefinitionId.

---

Create a new field definition

POST/odata/CustomFieldDefinition

Parameter	Type	Required	Description
Body	Delta<ApiCustomFieldDefinition>	✅	JSON object with the entity properties.

info

The ColumnName must be unique per table. Use a prefix like cf_ to easily distinguish custom fields from system fields.

---

Update a field definition

PATCH/odata/CustomFieldDefinition({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldDefinitionId.
Body	Delta<ApiCustomFieldDefinition>	✅	JSON object with the fields to update.

---

Delete a field definition

DELETE/odata/CustomFieldDefinition({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldDefinitionId.

warning

Deleting a field definition also removes all associated values from all objects. This action cannot be undone.

Returns 204 No Content on success.

---

CustomFieldPermission

The CustomFieldPermission entity controls access to custom fields. You can specify which users or roles are allowed to edit which fields.

Data Model

Property	Type	Description
CustomFieldPermissionId	guid	Unique ID of the permission.
CustomFieldDefinitionId	guid	ID of the associated field definition.
SubjectType	int	Type of permission. Values: 1 = User, 2 = Role.
SubjectId	guid	ID of the subject (user ID or role ID).
RoleType	int?	Role (optional, for role-based permissions). Values: 2 = Managers, 4 = Team, 8 = Partners, 16 = Customers, 32 = Additional, 64 = Project Request Reviewer, 128 = Additional 1, 256 = Additional 2, 512 = Additional 3, 1024 = Additional 4, 2048 = Additional 5.

Endpoints

Retrieve all field permissions for all fields

GET/odata/CustomFieldPermission

Supports OData query options.

---

Retrieve a field permission by ID

GET/odata/CustomFieldPermission({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldPermissionId.

---

Create a new field permission

POST/odata/CustomFieldPermission

Parameter	Type	Required	Description
Body	Delta<ApiCustomFieldPermission>	✅	JSON object with the permission properties.

---

Update a field permission

PATCH/odata/CustomFieldPermission({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldPermissionId.
Body	Delta<ApiCustomFieldPermission>	✅	JSON object with the fields to update.

---

Delete a field permission

DELETE/odata/CustomFieldPermission({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldPermissionId.

warning

Deleting a permission makes the custom field writable for all users who have write access to the corresponding entity.

Returns 204 No Content on success.

---

Retrieve blocked fields of an entity for the current user

GET/odata/CustomFieldPermission/GetBlockedFieldsForEntity(entityType={entityType},entityId={entityId})

Parameter	Type	Required	Description
entityType	string	✅	The entity type. Values: TimeEntry (0), LineItem (1), Budget (2), Document (3), MindMapNode (4), MindMap (5), Planning (6), TaskItem (7), Project (8), CheckList (9), FiscalPeriodFunding (10), Risk (11), Contact (12), PresetLineItem (101), Preset (102).
entityId	guid	✅	The ID of the specific entity.

Returns a list of custom fields that the current user is not allowed to edit.

---

CustomFieldSection

The CustomFieldSection entity allows you to organize custom field definitions into named groups within each entity type. Each section has a display name and a sort position.

Data Model

Property	Type	Description
CustomFieldSectionId	guid	Unique ID of the section.
TableName	string	Entity type the section belongs to. Values: TimeEntry (0), LineItem (1), Budget (2), Document (3), MindMapNode (4), MindMap (5), Planning (6), TaskItem (7), Project (8), CheckList (9), FiscalPeriodFunding (10), Risk (11), Contact (12), PresetLineItem (101), Preset (102).
DisplayName	string	Display name of the section in the user interface.
OrdinalPosition	int	Sort position of the section within its entity type.

Endpoints

Retrieve all custom field sections

GET/odata/CustomFieldSection

Supports OData query options.

---

Retrieve a section by ID

GET/odata/CustomFieldSection({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldSectionId.

---

Create a new section

POST/odata/CustomFieldSection

Parameter	Type	Required	Description
Body	object	✅	JSON object with the following fields: TableName (string, required) — The entity type for the section. DisplayName (string, required) — The display name of the section.

---

Update a section

PATCH/odata/CustomFieldSection({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldSectionId.
Body	object	✅	JSON object with the fields to update: DisplayName (string, optional) — The new display name. OrdinalPosition (int, optional) — The new sort position.

---

Delete a section

DELETE/odata/CustomFieldSection({key})

Parameter	Type	Required	Description
key	guid	✅	The CustomFieldSectionId.
targetSectionId	guid	✅	The ID of the section to move existing fields to before deleting.

warning

Deleting a section moves all its custom fields to the target section. There must be at least one other section for the same entity type.

Returns 204 No Content on success.

---

Dynamic Endpoints

Dynamic endpoints provide custom field values together with the standard properties of the entity in a single flat result set. Instead of querying CustomField separately and joining via ObjectId, you can read and filter custom field data directly on the entity.

Available Dynamic Entity Sets

Dynamic Endpoint	Base Entity
/odata/DynamicProject	Project
/odata/DynamicPlanning	Planning
/odata/DynamicTaskItem	TaskItem
/odata/DynamicBudget	Budget
/odata/DynamicLineItem	LineItem
/odata/DynamicTimeEntry	TimeEntry
/odata/DynamicContact	Contact (see Contacts)

Retrieve projects with included custom field columns

GET/odata/DynamicProject

Retrieve planning elements with included custom field columns

GET/odata/DynamicPlanning

Retrieve task items with included custom field columns

GET/odata/DynamicTaskItem

Retrieve budgets with included custom field columns

GET/odata/DynamicBudget

Retrieve line items with included custom field columns

GET/odata/DynamicLineItem

Retrieve time entries with included custom field columns

GET/odata/DynamicTimeEntry

Custom Field Column Naming

Custom field columns appear with the prefix CustomField_, followed by the ColumnName of the corresponding CustomFieldDefinition. For example, a field with ColumnName = Priority appears as CustomField_Priority in the dynamic response.

These prefixed columns can be used in all standard OData query options:

Query Option	Example
$select	$select=Name,CustomField_Priority
$filter	$filter=CustomField_Priority eq 'High'
$orderby	$orderby=CustomField_Priority asc

tip

Dynamic endpoints are read-only views. To update custom field values, use the CustomField PATCH or BatchUpdate endpoints described above.

---

OData Query Examples

Retrieve a custom field value

GET /odata/CustomField(Name='cf_Priority',ObjectId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Update a custom field value

PATCH /odata/CustomField(Name='cf_Priority',ObjectId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Content-Type: application/json

{
  "Value": "High"
}

Update multiple custom field values at once

POST /CustomField/BatchUpdate
Content-Type: application/json

[
  { "Name": "cf_Priority", "ObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "Value": "High" },
  { "Name": "cf_Region", "ObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "Value": "EMEA" }
]

Retrieve definitions for a specific table

GET /odata/CustomFieldDefinition?$filter=TableName eq 'Project'&$orderby=OrdinalPosition

Create a field definition

POST /odata/CustomFieldDefinition
Content-Type: application/json

{
  "ColumnName": "cf_RiskLevel",
  "DisplayName": "Risk Level",
  "TableName": "Project",
  "ColumnType": 0,
  "OrdinalPosition": 5,
  "WarningIfEmpty": false,
  "WriteProtectionEnabled": false
}

Update a field definition

PATCH /odata/CustomFieldDefinition('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
Content-Type: application/json

{
  "DisplayName": "Risk Assessment",
  "WarningIfEmpty": true
}

Filter permissions by field definition

GET /odata/CustomFieldPermission?$filter=CustomFieldDefinitionId eq xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Create a field permission

POST /odata/CustomFieldPermission
Content-Type: application/json

{
  "CustomFieldDefinitionId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "SubjectType": 0,
  "SubjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Update a field permission

PATCH /odata/CustomFieldPermission('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
Content-Type: application/json

{
  "RoleType": 1
}

Retrieve blocked fields for an entity

GET /odata/CustomFieldPermission/GetBlockedFieldsForEntity(entityType='Project',entityId=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Filter projects by custom field

GET /odata/DynamicProject?$filter=CustomField_Priority eq 'High'

Select and filter projects with custom fields

GET /odata/DynamicProject?$select=ProjectId,Name,CustomField_Priority,CustomField_Region&$filter=CustomField_Region eq 'EMEA'&$orderby=CustomField_Priority asc

tip

Combine $filter with $select to minimize response size. Use $top and $skip to paginate large result sets.