Profile attributes are custom fields on the contact profile that store data such as preferences, loyalty tier, or values synced from an external system. Engage uses them for personalization and as criteria in segmentation and targeting. This use case shows how to create a new profile attribute through the Engage API, so you can provision custom fields directly from your own systems.
Prerequisites
Before you begin, make sure you have valid authorization credentials. See Getting Started with Engage API for more information. A profile attribute has a data type — STRING, NUMBER, BOOLEAN, or DATE — and each account has a limited capacity per data type. Attribute creation runs asynchronously: the request returns a scheduled operation, and the attribute becomes available once that operation completes.
Procedure
Optionally, check the remaining capacity per data type with GET /profileAttributes/getCapacity and confirm the name is not already in use with GET /profileAttributes/validateName. Then create the attribute. The request body defines the attribute — at minimum a name and a dataType. Use description for an internal note, and set enumerated to true with enumeratedValues to restrict the attribute to a fixed list of values. To assign the attribute to specific channels, include assignedChannels with channel IDs returned by GET /profileAttributes/getAvailableChannels.
POST 'https://your-engage-domain.com/api/rest/profileAttributes/create'
{
"name": "loyalty_tier",
"dataType": "STRING",
"description": "Loyalty tier synced from the shop backend",
"enumerated": true,
"enumeratedValues": ["bronze", "silver", "gold"]
}The response is a scheduled operation result. Use its identifier to check the operation status; the attribute is available for personalization and segmentation once the operation has completed.
Conclusion
Creation does not take effect immediately — confirm the scheduled operation has completed before you reference the attribute. Creation fails if the name is already in use or the capacity for the chosen data type is exhausted, so checking validateName and getCapacity first avoids errors. Once available, the attribute can be listed with the attribute definition methods and set on contacts.
Related Topics
Validate a profile attribute name