Skip to main content
Creatio’s quarterly bookings reach 255% of prior-year results as enterprises adopt ai 
Version: 10.0

Segmentation Engine API endpoints

Level: advanced

The Segmentation Engine API in Creatio provides endpoints to manage audience segment membership, including segment actualization and segment membership reset, through REST API calls.

Actualize a segment​

Request string​

POST /0/rest/SegmentService/Actualize

Fill a segment by evaluating the entry rules defined on the Entry rules tab and the exit rules defined on the Exit rules tab of the segment page. Actualization performs a soft delete by setting the RemovedOn column on rows in the corresponding SysDataInSegment table.

Request headers​

Header

Description

Content-Type

The media type of the request body. For example, "application/json." Learn more: Content-Type Header Field (official RFC Editor documentation).

BPMCSRF

CSRF protection token. Must match the value of the BPMCSRF cookie.

Cookie

Contains the .ASPXAUTH session cookie and the BPMCSRF cookie required for cookie-based authentication. Use the BPMCSRF cookie value in every POST, PUT, DELETE request.

Request body​

Parameter

Type

Required

Description

segmentId

Guid

Yes

The ID of the "Segment" (SysDataSegment code) object record to actualize.

ExcludeCurrentMembersBeforeActualization

boolean

No

Specifies whether Creatio clears segment members in the Currently in segment expanded list on the Contacts tab of the segment page before actualization. Out of the box, the value is set to "false." If set to "true," Creatio marks all current segment members as removed and repopulates the segment from scratch based on the current entry filter data.

The same behavior is available in the UI through the "Replace — start fresh" option in the Segment resume mode field of the Resume and re-populate mini page that opens after clicking the Resume segment button on the segment page.

Response body​

Property

Type

Description

success

boolean

Indicates whether Creatio completed the actualization without errors related to the request data.

Available values

Value

Description

true

Creatio completed the actualization.

false

Creatio did not complete the actualization. The reasons for the unsuccessful actualization are provided in the errorMessage property.

segmentId

Guid

Echo of the requested segment ID.

status

string

The outcome of the actualization run. Returned only when "success": true.

Available values

Value

Description

completed

Creatio evaluated the entry and exit rules and actualized the segment.

skipped

Another actualization is already running for the same segment. Actualization is synchronous, so Creatio does not block the call: it returns "success": true with "status": "skipped" instead of running the actualization again.

startedOn

string

The date and time the actualization started, in UTC using the ISO 8601 format. Returned only when "success": true.

completedOn

string

The date and time the actualization completed, in UTC using the ISO 8601 format. Returned only when "success": true.

recordsRestored

integer

Previously removed members that matched again and were restored during this run. Returned only when "success": true.

recordsInserted

integer

New members inserted during this run. Returned only when "success": true.

recordsRemoved

integer

Members removed during this run because they no longer match the filter, or because their source record no longer exists (orphan cleanup). Returned only when "success": true.

totalMembers

integer

Total membership rows after the run, including soft-removed (exited) rows. Returned only when "success": true.

totalActiveMembers

integer

Active member count after the run. Mirrored into the "Current contacts" (RecordCount code) column on the "Segment" (SysDataSegment code) object. Returned only when "success": true.

errorMessage

string

The description of the error. Returned only when "success": false.

Actualization is idempotent: calling it again with an unchanged filter finds nothing new, so the endpoint returns "recordsInserted": 0 and "recordsRemoved": 0. To actualize the entire population, send a match-everything entry filter which selects every record of the target entity. A null or blank EntryFilterData value is not the same, since actualization rejects it because the segment entry filter is missing. Since Creatio batches the work internally, large segments actualize in multiple round-trips within the single call.

A configurable timeout limits how long a single actualization run can take. The timeout is managed by the "Segment candidate tables maintenance database command timeout (seconds)" (SegmentCandidateTableManagerDbCommandTimeout code) system setting. Out of the box, the value is set to "7200" seconds (2 hours), and it must be between "500" and "43200." When actualization hits the timeout, Creatio returns its default timeout error.

Usage example​

The following example actualizes the segment whose ID is "11111111-1111-1111-1111-111111111111."

curl -i -X POST "{Creatio URL}/0/rest/SegmentService/Actualize" \
  -H "Content-Type: application/json" \
  -H "BPMCSRF: {csrf-token}" \
  -H "Cookie: .ASPXAUTH={auth-token}; BPMCSRF={csrf-token}" \
  -d '{
    "segmentId": "11111111-1111-1111-1111-111111111111"
  }'

Truncate a segment​

Request string​

POST /0/rest/SegmentService/Truncate

Remove all segment members from the Currently in segment expanded list on the Contacts tab of the segment page. The entry rules on the Entry rules tab and the exit rules on the Exit rules tab of the segment page remain unchanged.

Unlike actualization, which performs a soft delete by setting the RemovedOn column on rows in the corresponding SysDataInSegment table, the Truncate endpoint performs a hard delete that fully empties the table. After the operation, the "Current contacts" (RecordCount code) column on the "Segment" (SysDataSegment code) object resets to "0" and the "Segment status" column in the Segments section resets to "Draft."

Request headers​

Header

Description

Content-Type

The media type of the request body. For example, "application/json." Learn more: Content-Type Header Field (official RFC Editor documentation).

BPMCSRF

CSRF protection token. Must match the value of the BPMCSRF cookie.

Cookie

Contains the .ASPXAUTH session cookie and the BPMCSRF cookie required for cookie-based authentication. Use the BPMCSRF cookie value in every POST, PUT, DELETE request.

Request body​

Parameter

Type

Required

Description

segmentId

Guid

Yes

The ID of the "Segment" (SysDataSegment code) object record to truncate.

Response body​

Property

Type

Description

success

boolean

Indicates whether Creatio completed the truncation without errors related to the request data.

Available values

Value

Description

true

Creatio completed the truncation, including calls made against a segment that already has no members.

false

Creatio did not complete the truncation. The reasons for the unsuccessful truncation are provided in the errorMessage property.

segmentId

Guid

Echo of the requested segment ID.

status

string

The outcome of the truncation. Returned only when "success": true.

Available values

Value

Description

truncated

Creatio truncated the segment. Creatio returns this value even when the segment already has no members.

errorMessage

string

The description of the error. Returned only when "success": false.

Creatio does not compute the deleted-row count, so a successful response omits rowsDeleted entirely. Do not rely on this field. Creatio rejects the call while the segment is mid-actualization.

Usage example​

The following example truncates the segment whose ID is "11111111-1111-1111-1111-111111111111."

curl -i -X POST "{Creatio URL}/0/rest/SegmentService/Truncate" \
  -H "Content-Type: application/json" \
  -H "BPMCSRF: {csrf-token}" \
  -H "Cookie: .ASPXAUTH={auth-token}; BPMCSRF={csrf-token}" \
  -d '{
    "segmentId": "11111111-1111-1111-1111-111111111111"
  }'

Error handling​

Both endpoints return a fixed set of HTTP status codes. Check the success property of the response body instead of the HTTP status code to detect errors related to the request data.

HTTP status code

Description

200 OK

Creatio returns this status even for errors related to the request data, for example, an invalid segment ID, filter errors, or a truncate conflict. Check the success property of the response body instead of the HTTP status code to detect such errors.

400 Bad Request

The request body is malformed.

401 Unauthorized,
403 Forbidden,
5xx server error

The session is missing or invalid.

See also​

Manage segments using Segmentation Engine API