Segments define target audiences in Engage — dynamic sets of contacts that match conditions on profile data and behavior and update automatically as the data changes. They are used to target message sendouts, feed automation workflows, and build A/B or pilot groups. This use case shows how to create a segment and make it live through the Engage API, so you can automate audience creation 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 segment is first saved as a draft and then published; publishing validates the plan.
Procedure
Optionally, fetch the plan JSON schema with GET /segmentation/schema and validate your plan against it first. Then create the plan. The request body is a wrapper whose json field carries the plan document — containing at least name and nodes — as an escaped string.
POST 'https://your-engage-domain.com/api/rest/segmentation/create'
{
"json": "{\"name\":\"High-value customers\",\"nodes\":[ ... ]}"
}The response returns the new plan's id. Publish it to make it the live version:
POST 'https://your-engage-domain.com/api/rest/segmentation/publish?id=<planId>'Conclusion
A draft may save even with incomplete criteria, but publish fully validates the plan and rejects an invalid one with a 400 response. After publishing, you can check the audience size with getCount or preview.