Custom Properties API

This document describes the Custom Properties endpoints for Data Models in the DataService API v2.

Base URL

/api/v2/DataModels

Endpoints

1. Get Custom Properties Collection

Retrieves a filtered collection of custom properties.

Endpoint: GET /api/v2/DataModels/CustomProperties

Query Parameters:

Parameter	Type	Required	Description
ModelId	Guid	No	Filter by specific data model identifier
PagingFilter.Offset	int	No	Number of records to skip
PagingFilter.Limit	int	No	Maximum number of records to return

Response Statuses:

Status Code	Description
200 OK	Successfully retrieved collection
401 Unauthorized	Missing or invalid authentication

Response Body:

{
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "modelId": "8b5f7c12-1234-4abc-9def-456789012345",
      "organizationId": "ASOLEU",
      "code": "CustomerRating",
      "name": "Customer Rating",
      "description": "Rating assigned to customer",
      "isCollection": false,
      "isLocalized": false,
      "fieldType": 4,
      "referencedEntityTypeIds": null,
      "fieldValidations": []
    }
  ],
  "totalCount": 1
}

Example Request:

GET /api/v2/DataModels/CustomProperties?ModelId=8b5f7c12-1234-4abc-9def-456789012345&PagingFilter.Offset=0&PagingFilter.Limit=10

---

2. Get Custom Property by ID

Retrieves a specific custom property by its unique identifier.

Endpoint: GET /api/v2/DataModels/CustomProperties/{id}

Path Parameters:

Parameter	Type	Required	Description
id	Guid	Yes	The custom property identifier

Response Statuses:

Status Code	Description
200 OK	Successfully retrieved the custom property
404 Not Found	Custom property with the specified ID does not exist

Response Body:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "modelId": "8b5f7c12-1234-4abc-9def-456789012345",
  "organizationId": "ASOLEU",
  "code": "CustomerRating",
  "name": "Customer Rating",
  "description": "Rating assigned to customer",
  "isCollection": false,
  "isLocalized": false,
  "fieldType": 4,
  "referencedEntityTypeIds": null,
  "fieldValidations": [
    {
      "validation": "Range",
      "minimum": 1,
      "minimumIsExclusive": false,
      "maximum": 5,
      "maximumIsExclusive": false
    }
  ]
}

Example Request:

GET /api/v2/DataModels/CustomProperties/3fa85f64-5717-4562-b3fc-2c963f66afa6

---

3. Get Custom Property by Code

Retrieves a custom property by its code (name) within the organization context.

Endpoint: GET /api/v2/DataModels/CustomProperties/ByCode/{code}

Path Parameters:

Parameter	Type	Required	Description
code	string	Yes	The custom property code

Response Statuses:

Status Code	Description
200 OK	Successfully retrieved the custom property
401 Unauthorized	Missing or invalid authentication
404 Not Found	Custom property with the specified code does not exist

Response Body:

Same as Get Custom Property by ID.

Example Request:

GET /api/v2/DataModels/CustomProperties/ByCode/CustomerRating

---

4. Create Custom Property

Creates a new custom property for a specific data model.

Endpoint: POST /api/v2/DataModels/{modelId}/CustomProperties

Path Parameters:

Parameter	Type	Required	Description
modelId	Guid	Yes	The data model identifier

Request Body:

Field	Type	Required	Description
organizationId	string	No	Organization identifier (uses current context if not provided)
code	string	Yes	Unique code for the custom property
name	LocalizedValue<string>	Yes	Localized display name
description	LocalizedValue<string>	No	Localized description
isCollection	bool	Yes	Whether the property holds multiple values
isLocalized	bool	Yes	Whether the property value is localized
fieldType	DataModelFieldType	Yes	The data type of the field
referencedEntityTypeIds	Guid[]	No	Referenced entity type IDs (for LookupEntity/NestedEntity types)
fieldValidations	DataModelFieldDefinitionValidation[]	No	Validation rules for the field

Response Statuses:

Status Code	Description
201 Created	Custom property successfully created
409 Conflict	Custom property with the same code already exists

Response Body:

Returns the created DataModelCustomPropertyDefinition object with the Location header pointing to the new resource.

Example Request:

POST /api/v2/DataModels/8b5f7c12-1234-4abc-9def-456789012345/CustomProperties
Content-Type: application/json

{
  "code": "CustomerRating",
  "name": {
    "values": [
      { "culture": "en-US", "value": "Customer Rating" },
      { "culture": "cs-CZ", "value": "Hodnocení zákazníka" }
    ]
  },
  "description": {
    "values": [
      { "culture": "en-US", "value": "Rating assigned to customer (1-5)" }
    ]
  },
  "isCollection": false,
  "isLocalized": false,
  "fieldType": 4,
  "fieldValidations": [
    {
      "validation": "Range",
      "minimum": 1,
      "minimumIsExclusive": false,
      "maximum": 5,
      "maximumIsExclusive": false
    }
  ]
}

Example Response:

HTTP/1.1 201 Created
Location: /api/v2/DataModels/CustomProperties/3fa85f64-5717-4562-b3fc-2c963f66afa6

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "modelId": "8b5f7c12-1234-4abc-9def-456789012345",
  "organizationId": "ASOLEU",
  "code": "CustomerRating",
  "name": "Customer Rating",
  "description": "Rating assigned to customer (1-5)",
  "isCollection": false,
  "isLocalized": false,
  "fieldType": 4,
  "referencedEntityTypeIds": null,
  "fieldValidations": [
    {
      "validation": "Range",
      "minimum": 1,
      "minimumIsExclusive": false,
      "maximum": 5,
      "maximumIsExclusive": false
    }
  ]
}

---

5. Update Custom Property

Updates an existing custom property.

Endpoint: PUT /api/v2/DataModels/CustomProperties/{id}

Path Parameters:

Parameter	Type	Required	Description
id	Guid	Yes	The custom property identifier

Query Parameters:

Parameter	Type	Required	Default	Description
allowBreakingChanges	bool	No	false	Allow changes to FieldType, IsCollection, IsLocalized, or Validations

Request Body:

Field	Type	Required	Description
name	LocalizedValue<string>	Yes	Localized display name
description	LocalizedValue<string>	No	Localized description
isCollection	bool	Yes	Whether the property holds multiple values
isLocalized	bool	Yes	Whether the property value is localized
fieldType	DataModelFieldType	Yes	The data type of the field
referencedEntityTypeIds	Guid[]	No	Referenced entity type IDs
fieldValidations	DataModelFieldDefinitionValidation[]	No	Validation rules for the field

Response Statuses:

Status Code	Description
200 OK	Custom property successfully updated
400 Bad Request	Breaking change attempted without allowBreakingChanges=true
404 Not Found	Custom property with the specified ID does not exist

Breaking Changes:

The following changes are considered breaking and require allowBreakingChanges=true:

• Changing fieldType
• Changing isCollection
• Changing isLocalized
• Changing fieldValidations

Example Request (Non-breaking change):

PUT /api/v2/DataModels/CustomProperties/3fa85f64-5717-4562-b3fc-2c963f66afa6
Content-Type: application/json

{
  "name": {
    "values": [
      { "culture": "en-US", "value": "Updated Customer Rating" }
    ]
  },
  "description": {
    "values": [
      { "culture": "en-US", "value": "Updated description" }
    ]
  },
  "isCollection": false,
  "isLocalized": false,
  "fieldType": 4,
  "fieldValidations": []
}

Example Request (Breaking change):

PUT /api/v2/DataModels/CustomProperties/3fa85f64-5717-4562-b3fc-2c963f66afa6?allowBreakingChanges=true
Content-Type: application/json

{
  "name": {
    "values": [
      { "culture": "en-US", "value": "Customer Rating" }
    ]
  },
  "isCollection": false,
  "isLocalized": false,
  "fieldType": 5,
  "fieldValidations": []
}