Segments

POST (create) a Segment

Changed on

Use this method to create a new segment. You create segments to target a subset of your contacts that meet your specific criteria for a marketing campaign. The segment name must be unique. The segment_criteria requires single-string escaped JSON. Constant Contact uses the contact data that you specify in the segment_criteria to evaluate and identify the contacts you want to target. Contact data can be grouped from different data sources, including:

  • tracking: Supports or and and groups.

  • contact: Supports or and and groups.

  • list_membership: Supports or groups.

  • tags: Supports or groups.

If you do not specify list_membership as criteria, Constant Contact evaluates all contacts in your account. To avoid returning a 400 error response, when specifying the segment_criteria do not request more than 500 email campaigns or a date range greater than 1825 days (5 years) be evaluated.

For more use case information, see the Segments Overview in the API guide.

post/segments

Request

  • Base URL
    https://api.cc.email/v3
  • URL
    https://api.cc.email/v3/segments
  • Auth
    • OAuth 2
      Implicit: https://authz.constantcontact.com/oauth2/default/v1/authorize
      Scopes: contact_data
    • or OAuth 2
      Authorization code: https://authz.constantcontact.com/oauth2/default/v1/authorize
      Token URL: https://authz.constantcontact.com/oauth2/default/v1/token scopes: contact_data

Request body

namestring required

The segment's unique descriptive name.

segment_criteriastring required

The <code>segment_criteria</code> specifies the contact data that Constant Contact uses to evaluate and identify contacts that meet your criteria. The <code>segment_criteria</code> must be formatted as single-string escaped JSON. The top-level <code>group</code> <code>type</code> must be <code>add</code>.

Example request

{
  "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}"
}

Response

Segment successfully created.

namestring

The segment's unique descriptive name.

segment_criteriastring

The segment's contact selection criteria formatted as single-string escaped JSON.

segment_idinteger

The system generated number that uniquely identifies the segment.

created_atstring date-time

The system generated date and time (ISO-8601) that the segment was created.

edited_atstring date-time

The system generated date and time (ISO-8601) that the segment's <code>name</code> or <code> segment_criteria</code> was last updated.

Example response

{
  "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}",
  "segment_id": 14,
  "created_at": "2019-04-25T11:08:00.000Z",
  "edited_at": "2019-04-25T11:08:00.000Z"
}

Changes