Create segment API

Learn more about creating a new segment.

A segment is a saved rule that selects profiles based on entity and interaction attributes. Use the Create segment to save the segment in your tenant. You can also create a segment in Hub.

HTTP method and endpoint

Use the following HTTP method and endpoint path to create a segment.

POST {platformUrl}/reltio/api/{tenantId}/segments

Replace {platformUrl} with your Reltio platform base URL.

The following table describes the endpoint path parameters.


Parameter	Type	Required	Description
`tenantId`	String	Yes	ID of the tenant where you create the segment. Example: `ce5627DYnQ6abcD`

Request headers

The following request headers must be included.


Header	Value	Required
`Authorization`	Bearer `<accessToken>`.	Yes
`Content-Type`	`application/json`	Yes

Request body

The following table describes the request body parameters required to create a segment.


Parameter	Type	Required	Description	Accepted values / Default
`label`	String	Yes	Name of the segment.	Any string. Example: `Platinum Members`
`sharing`	String	Yes	Who can see the segment.	`private` or `public`.
`rule`	String	Yes	Defines the criteria for the segment by specifying the attributes and conditions used to select profiles. Your role must have `READ` access to every entity type, interaction type, and attribute referenced in the `rule`. If your role lacks `READ` access, Reltio does not save the segment and returns an error. To grant access, see Set Permissions.	Segment filter expression.
`schedule`	Object	No	When to run a batch segment.	Object with `startTime` and `repeat`.
`schedule.startTime`	String	No	Start time for the batch schedule.	ISO 8601 datetime. Example: `2000-10-31T01:30:00.000-05:00`.
`schedule.repeat`	String	No	Frequency at which the batch segment runs.	iCal RRULE string. Example: `RRULE:FREQ=WEEKLY;BYDAY=FR`. Minimum frequency: once per hour.
`description`	String	No	Description of the segment.	Any string.
`parentId`	String	No	ID of the folder that contains the segment.	Folder ID.
`favorite`	Boolean	No	Adds the segment to your Hub favorites.	`true` or `false`.
`integrationIDs`	Array of String	No	IDs of the integrations used for activation.	Array of integration IDs.

Example request

The following example shows how a complete request is structured to create a segment.

POST {platformUrl}/reltio/api/{tenantId}/segments
[
  {
    "label": "Platinum Members",
    "sharing": "private",
    "rule": "equals(entity.attributes.Gender, 'M') and range(entity.attributes.Age, 30, 40) and equals(entity.attributes.Address.City, 'NY') and gte(count(equals(interaction.type, 'configuration/interactionTypes/Meeting')), 2)",
    "schedule": {
      "startTime": "2000-10-31T01:30:00.000-05:00",
      "repeat": "RRULE:FREQ=WEEKLY;BYDAY=FR"
    },
    "description": "<description provided by the user>"
  }
]

Response body

The following table describes the fields returned in the response body when the request succeeds.


Field	Type	Description
`index`	Number	Index of the request item that produced this result.
`object`	Object	Details of the created segment.
`object.id`	String	ID of the segment.
`object.label`	String	Name of the segment.
`object.owner`	String	Owner of the segment.
`object.sharing`	String	Defines who can view the segment.
`object.type`	String	Type of segment.
`object.status`	String	Current status of the segment.
`object.rule`	String	Filter expression that defines the segment criteria.
`object.schedule`	Object	Schedule for running a batch segment.
`object.schedule.startTime`	String	Start time for the batch schedule.
`object.schedule.repeat`	String	Frequency at which the batch segment runs.
`object.description`	String	Description of the segment.

Example response

The following example shows a successful response.

[
  {
    "index": 0,
    "object": {
      "id": "S1",
      "label": "Platinum Members",
      "owner": "Cris.Davis@mail.com",
      "sharing":"private",
      "type": "batch",
      "status": "submitted",
      "rule": "equals(entity.attributes.Gender, 'M') and range(entity.attributes.Age, 30, 40) and equals(entity.attributes.Address.City, 'NY') and gte(count(equals(interaction.type, 'configuration/interactionTypes/Meeting')), 2)",
      "schedule": {
          "startTime": "2000-10-31T01:30:00.000-05:00",
          "repeat":"RRULE:FREQ=WEEKLY;BYDAY=FR"
      },
      "description": "<description provided by the user>",
    }
  }
]

Error codes and recommended actions

The following table lists the possible error responses returned by Create segment.


HTTP status	Error code	Description	Recommended action
`200 OK`	`800`	Suggestion: If your role lacks `READ` on any entity type, interaction type, or attribute named in the `rule`, Reltio rejects the segment.	Grant `READ` with Set Permissions, then retry.

Unify and manage your data