Skip to content

Contact List — Segment

A segment is a saved contact filter on a contact list. Campaigns can be restricted to one or more segments (the segments[] parameter of Campaign), and the contacts of a segment can be listed with GET /contact_list/<list>/contacts?segment=<segment>.

Endpoints

Method URL
GET /contact_list/<list>/segment/<segment>
POST /contact_list/<list>/segment
PUT /contact_list/<list>/segment/<segment>
DELETE /contact_list/<list>/segment/<segment>

All verbs require write access to the list.

GET /contact_list/<list>/segment/<segment>

Parameter Type Description
page int Page of matching contacts to return. Defaults to 1.
pagesize int Contacts per page. Defaults to 10.

Returns: The segment, one page of the contacts that match it (contacts), the number of matching contacts (contactCount) and the number of pages (contactPageCount).

Example:

curl -u "username:api_key" -H "Accept: application/json" \
  https://app.duo.pt/contact_list/{list_id}/segment/{segment_id}

Response:

{
  "success": true,
  "data": {
    "page": 1,
    "pagesize": 10,
    "contact_list": {
      "id": 1,
      "owner": 1,
      "name": "Example...",
      "default_email_out": null,
      "unsubscribe_message": "Click the button below to unsubscribe from the list.",
      "email_out_custom_fields": null,
      "double_optin": false,
      "optout_allowed": true,
      "optout_category": null,
      "optin_email": null,
      "optin_sms": null,
      "shared_with_children": false,
      "read_shared_with_children": false,
      "segments": null
    },
    "segment": {
      "id": 7,
      "list": 1,
      "name": "Subscribed at example.com",
      "filter": {
        "operator": "AND",
        "arguments": [
          {"operator": "ENDSWITH", "leftArg": "email", "rightArg": "@example.com"},
          {"operator": "==", "leftArg": "subscription_state", "rightArg": "SUBSCRIBED"}
        ]
      }
    },
    "contacts": [
      {
        "contact_id": 17137542,
        "subscription_status": "SUBSCRIBED",
        "bouncing": false,
        "telephone": "351910000001",
        "email": "contact@example.com"
      }
    ],
    "contactCount": 1,
    "contactPageCount": 1,
    "contact_count": {
      "subscribed": { "count": 1 }
    }
  }
}

contact_count.subscribed.count is the total number of contacts that match the segment, whatever their subscription status.

POST /contact_list/<list>/segment

Parameter Type Description
name string Segment name
filter JSON string Required. The contact filter, with the same syntax as the filter parameter of Contacts.

Warning

The filter is not validated when the segment is saved. A filter that is not valid JSON, or that uses an unknown leftArg or operator, only fails when the segment is used. Test the filter first with GET /contact_list/<list>/contacts.

Returns: The contact list and the new segment.

Example:

curl -u "username:api_key" -H "Accept: application/json" \
  -d "name=Subscribed+at+example.com" \
  --data-urlencode 'filter={"operator":"AND","arguments":[{"operator":"ENDSWITH","leftArg":"email","rightArg":"@example.com"},{"operator":"==","leftArg":"subscription_state","rightArg":"SUBSCRIBED"}]}' \
  https://app.duo.pt/contact_list/{list_id}/segment

Response:

{
  "success": true,
  "data": {
    "contact_list": { "id": 1, "owner": 1, "name": "Example..." },
    "segment": {
      "id": 7,
      "list": 1,
      "name": "Subscribed at example.com",
      "filter": {
        "operator": "AND",
        "arguments": [
          {"operator": "ENDSWITH", "leftArg": "email", "rightArg": "@example.com"},
          {"operator": "==", "leftArg": "subscription_state", "rightArg": "SUBSCRIBED"}
        ]
      }
    },
    "success": true
  }
}

PUT /contact_list/<list>/segment/<segment>

Same payload as POST.

Send the update as a POST with x-verb=PUT (see HTTP Verb Tunneling).

Returns: The contact list and the edited segment.

Example:

curl -u "username:api_key" -H "Accept: application/json" \
  -d "x-verb=PUT&name=Bouncing+contacts" \
  --data-urlencode 'filter={"operator":"==","leftArg":"bounce_state","rightArg":"true"}' \
  https://app.duo.pt/contact_list/{list_id}/segment/{segment_id}

Response:

{
  "success": true,
  "data": {
    "contact_list": { "id": 1, "owner": 1, "name": "Example..." },
    "segment": {
      "id": 7,
      "list": 1,
      "name": "Bouncing contacts",
      "filter": {"operator": "==", "leftArg": "bounce_state", "rightArg": "true"}
    },
    "success": true
  }
}

DELETE /contact_list/<list>/segment/<segment>

Payload: No payload.

Returns: The deleted segment (in segment and in result).

Example:

curl -u "username:api_key" -H "Accept: application/json" -X DELETE \
  https://app.duo.pt/contact_list/{list_id}/segment/{segment_id}

Response:

{
  "success": true,
  "data": {
    "contact_list": { "id": 1, "owner": 1, "name": "Example..." },
    "segment": {
      "id": 7,
      "list": 1,
      "name": "Bouncing contacts",
      "filter": {"operator": "==", "leftArg": "bounce_state", "rightArg": "true"}
    },
    "result": {
      "id": 7,
      "list": 1,
      "name": "Bouncing contacts",
      "filter": {"operator": "==", "leftArg": "bounce_state", "rightArg": "true"}
    }
  }
}