Retrieve Custom Attribute List: /settings/custom_attributes
Purpose
This endpoint retrieves a paginated list of all custom attributes configured in the system. It is useful for determining what additional fields are available for various entities (example: accounts, items, sales, purchases, custom objects).
Use Case
- Custom attributes are the building block of Custom forms and Custom Objects.
- Developers can dynamically fetch attribute definitions to build UI forms or validate data before sending it to other endpoints.
- Integration scripts can map custom attributes between systems.
Path Parameters
No path parameter is required for this endpoint.
Query Parameters
No path parameter is required for this endpoint.
Request Body
No request body is required for this endpoint.
Response
The API returns a JSON object with two main parts: custom attributes and pagination. Custom attributes is an array of objects, each describing a custom attribute with its uuid, status, name, display name, type, optional limits (min value, max value, max length). The use in array lists resources where the attribute is applicable, along with details like whether it is required, unique, enabled, and associated account/item/user groups. If the attribute is a dropdown, the options array contains its selectable values. The encrypt data field indicates if the attribute’s data is encrypted. Pagination provides record count, page size, offset, and links to previous or next pages.
Response Body
{
"custom_attributes": [
{
"uuid": "{{custom_attribute_uuid_1}}",
"status": "{{status}}",
"name": "{{custom_attribute_name_1}}",
"display_name": "{{custom_attribute_display_name_1}}",
"type": "{{custom_attribute_type_1}}",
"min_value": "{{min_value}}",
"max_value": "{{max_value}}",
"max_length": "{{max_length}}",
"use_in": [
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
}
],
"options": [
{
"display_order": "{{option_display_order}}",
"name": "{{option_name}}"
}
],
"encrypt_data": "{{is_encrypted}}"
},
{
"uuid": "{{custom_attribute_uuid_2}}",
"status": "{{status}}",
"name": "{{custom_attribute_name_2}}",
"display_name": "{{custom_attribute_display_name_2}}",
"type": "{{custom_attribute_type_2}}",
"min_value": "{{min_value}}",
"max_value": "{{max_value}}",
"max_length": "{{max_length}}",
"use_in": [
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
}
],
"options": [
{
"display_order": "{{option_display_order}}",
"name": "{{option_name}}"
}
],
"encrypt_data": "{{is_encrypted}}"
}
],
"pagination": {
"records": "{{total_records}}",
"limit": "{{limit_per_page}}",
"offset": "{{current_offset}}",
"previous_page": "{{previous_page_url}}",
"next_page": "{{next_page_url}}"
}
}
| Attribute | Type | Description |
|---|---|---|
| uuid | String | Unique identifier of the custom attribute. |
| status | String | Status of the custom attribute (example: ACTIVE, INACTIVE). |
| name | String | Internal name of the attribute (used as a system reference). |
| display_name | String | User-friendly display name of the attribute. |
| type | String | Data type of the attribute (example: STRING, NUMBER, DATE_TIME, BOOLEAN, DROPDOWN, FILE). |
| min_value | String | Minimum value allowed for the attribute, if applicable. Empty if not defined. |
| max_value | String | Maximum value allowed for the attribute, if applicable. Empty if not defined. |
| max_length | String | Maximum character length (for string-based attributes). Empty if not defined. |
| use_in | Array | List of usage contexts, showing where the attribute is applied and any restrictions. |
| options | Array | List of selectable options (for DROPDOWN attributes), each containing a display_order and name. |
| encrypt_data | String | Indicates whether the attribute’s data is encrypted (true or false). |
Retrieve Specific Custom Attribute Details: /settings/custom_attributes/{custom_attribute_uuid}
Purpose
This API retrieves detailed information about a specific custom attribute using its unique identifier (UUID).
Use Case
- Display details of a specific custom attribute.
- Validate or process data related to a particular custom attribute.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
| custom_attribute_uuid | string | The unique identifier of the custom attribute to retrieve. |
Query Parameters
No path parameter is required for this endpoint.
Request Body
No request body is required for this endpoint.
Response
The API returns a JSON object containing a single custom attribute object. This object provides detailed metadata about the specified custom attribute, including its uuid, status, system name, user-friendly display name, and type. Optional limits such as min value, max value, and max length may be present depending on the type. The use in array lists resources where the attribute is applicable, along with details like whether it is required, unique, enabled, and associated account/item/user groups. If the attribute is a dropdown, the options array contains its selectable values. The encrypt data field indicates if the attribute’s data is encrypted.
Response Body
{
"custom_attribute": {
"uuid": "{{custom_attribute_uuid}}",
"status": "{{status}}",
"name": "{{custom_attribute_name}}",
"display_name": "{{custom_attribute_display_name}}",
"type": "{{custom_attribute_type}}",
"min_value": "{{min_value}}",
"max_value": "{{max_value}}",
"max_length": "{{max_length}}",
"use_in": [
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_1}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_2}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_3}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_4}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_5}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_6}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_7}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_8}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_9}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_10}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_11}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_12}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
},
{
"associated_account_groups": [],
"associated_item_groups": [],
"associated_user_groups": [],
"required": "{{is_required}}",
"resource": "{{resource_name_13}}",
"unique": "{{is_unique}}",
"enabled": "{{is_enabled}}"
}
],
"options": [],
"encrypt_data": "{{is_encrypted}}"
}
}
| Attribute | Type | Description |
|---|---|---|
| uuid | string | Unique identifier of the custom attribute. |
| status | string | Current status of the attribute (example: ACTIVE). |
| name | string | System name of the custom attribute. |
| display_name | string | Human-readable name shown in the UI. |
| type | string | Data type of the attribute (example: STRING, NUMBER, QUANTITY, DROPDOWN, DATE_TIME, BOOLEAN, FILE, MONEY). |
| min_value | string | Minimum allowed value, if applicable. Empty if not defined. |
| max_value | string | Maximum allowed value, if applicable. Empty if not defined. |
| max_length | string | Maximum string length, if applicable. Empty if not defined. |
| use_in | array | List of resources where this attribute is used, including flags for required, unique, enabled, and associated groups. |
| options | array | List of selectable options for dropdown-type attributes; empty if not applicable. |
| encrypt_data | string | Indicates whether the attribute’s data is encrypted (true or false). |