SAP Emarsys Filter API

openapi: 3.2.0
info:
  title: Emarsys Core API - Segments endpoint batch Filter API
  description: In this batch you may find endpoints related to segments.
  version: v2
servers:
- url: https://api.emarsys.net/api
tags:
- name: Filter
paths:
  /v2/filter:
    put:
      summary: Create a Segment
      description: 'Creates a segment based on the specified contact and email behavior criteria.


        ### Overview

        Critera are represented as JSON object nodes in the request body. The relationship between the nodes is defined by the following:

        - Grouping operators link filter conditions with a logical AND or OR operator using the `type` property.

        - The node hierarchy correspond to the structure of the filters.


        For easier understanding of the nested contact criteria, see the configuration of filter conditions in the Emarsys application:


        ![Filter conditions in the Emarsys application](https://raw.githubusercontent.com/emartech/developer-hub-public-assets/master/assets/images/filter-conditions.png "Filter conditions in the Emarsys application")


        ### Node Structure

        Nodes can either be conjunctive or a criteria nodes. The function of each node is defined in the `type` property.

        - **Conjunctive nodes:** Nodes with a grouping operator `and` or `or` establish the relationship between parent and children nodes, and do not have any other property.

        - **Criteria nodes:** Nodes with the `criteria` property define a filter condition.


        | Criterion Type | Mandatory Properties | Optional Properties |

        | --- | --- | --- |

        | Contact criteria | - field<br>- operator<br>- value ||

        | Behavior criteria | - criteria | - time_restriction |


        **Important:**

        - Either one contact or behavior criteria must be specified in the request.

        - Nested nodes are specified in a `children` array of the JSON payload. See the Request Body section for details.


        **Note:** Mobile behavior, geolocation, and Smart Insight criteria are not supported using the API at the moment.'
      operationId: createSegment
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Unique name of the contact segment.
                description:
                  type: string
                  description: The description of the contact segment.
                baseContactListId:
                  type: string
                  description: 'Creates a segment based on a contact list.


                    **Note**: Use the value *0* to use all available contacts.'
                contactCriteria:
                  type: object
                  description: The new contact criteria.
                  properties:
                    type:
                      type: string
                      enum:
                      - and
                      - or
                      - criteria
                      description: 'Defines the function of each node.

                        - The grouping operator that defines the relationship between filter nodes.

                        - The value `critera` indicates that the node is a contact criteria.'
                      default: and
                    field_id:
                      type: string
                      description: The field_id used as criterion. For more information, see the [SAP Emarsys system fields](https://help.sap.com/docs/SAP_EMARSYS/5d44574160f44536b0130abf58cb87cc/fdf56fb974c110149470d0c1a7fb5ee9.html?locale=en-US).
                    operator:
                      type: string
                      description: The logical operator for comparing the specified field and its value.
                    value:
                      type: string
                      description: The value of the specified field.
                behaviourCriteria:
                  type: object
                  properties:
                    criteria:
                      type: string
                      enum:
                      - response_open_click
                      - response_click
                      - bounce
                      - noresponse_open_click
                      - noresponse_click
                      description: Defines a behavior criterion.
                    time_restriction:
                      type: string
                    type:
                      type: string
                      enum:
                      - and
                      - or
                      - criteria
                      description: 'Defines the function of each node.

                        - The grouping operator that defines the relationship between filter nodes.

                        - The value `critera` indicates that the node is a contact criteria.'
              required:
              - name
              x-examples:
              - name: summer_sale
                description: gender_based
                baseContactListId: '123456'
                contactCriteria:
                  type: and
                  children:
                  - type: criteria
                    field: gender
                    operator: equals
                    value: male
                  - type: and
                    children:
                    - type: and
                      children:
                      - type: criteria
                        field: email
                        operator: not_empty
                        value: is_not_empty
                      - type: criteria
                        field: email
                        operator: contains
                        value: '@gmail.com'
                      - type: criteria
                        field: email_valid
                        operator: equals
                        value: 'true'
                      - type: criteria
                        field: optin
                        operator: equals
                        value: 'true'
                      - criteria: response_open_click
                        type: criteria
                        time_restriction: between_dates
                        from_date: '2016-08-26'
                        to_date: '2016-08-31'
                      - criteria: response_click
                        type: criteria
                        time_restriction: between_days
                        from_day: '0'
                        to_day: '3'
                      - criteria: bounce
                        type: criteria
                        time_restriction: last_days
                        from_day: '0'
      tags:
      - Filter
  /v2/filter/{segmentId}:
    get:
      summary: List Segments
      description: Generates a list of segments.
      operationId: listSegments
      parameters:
      - name: segmentId
        in: path
        description: The identifier of the segment. If provided, returns the details of the specified only.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: array
                    description: The requested data.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: The segment identifier.
                        name:
                          type: string
                          description: The name of the segment.
                        type:
                          type: string
                          description: 'The segment type.


                            **Typical values:** `standard`, `combined`, `relational`, `ai`'
                        tags:
                          type: array
                          description: 'Additional information about the segment.


                            | Value | Description |

                            | --- | --- |

                            | `ai` | The segment is an AI segment, or it contains an AI segment (if combined) |'
                          items:
                            type: string
                            enum:
                            - ai
                        criteriaTypes:
                          type: array
                          enum:
                          - geo
                          - behavior
                          - si
                          - contact
                          description: 'The criteria types used in the segment.


                            **Notes:**

                            - Applies to standard segments only.

                            - Not returned when a single segment is requested.'
                          items:
                            type: string
                        baseContactListId:
                          type: integer
                          description: 'The identifier of contact list the segment is based on. The value *0* means that it is based on all contacts.


                            **Notes:**

                            - Applies to standard segments only.

                            - Not returned when a single segment is requested.'
                        predefinedSegmentId:
                          type: integer
                          description: 'The identifier of the predefined segment.


                            **Note:** Not returned when a single segment is requested.'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      x-internal: false
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/{segmentId}/contact_criteria:
    put:
      summary: Update Contact Criteria in a Segment
      description: 'Updates the contact criteria of a specific segment.


        For details on how the response body is structured, see [Create a segment](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NDY) endpoint.'
      operationId: updateContactCriteriaInSegment
      parameters:
      - name: segmentId
        in: path
        description: 'The segment identifier.


          **Note:** The identifier must not be *0*.'
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      type:
                        type: string
                        enum:
                        - and
                        - or
                        description: The grouping operator that defines the relationship between filter nodes.
                      children:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - and
                              - or
                              - criteria
                              description: 'Defines the function of each node.

                                - The grouping operator that defines the relationship between filter nodes.

                                - The value `critera` indicates that the node is a contact criteria.'
                            field:
                              type: string
                              description: The field name used as criterion.
                            operator:
                              type: string
                              description: The logical operator for comparing the specified field and its value.
                            value:
                              type: string
                              description: The value of the specified field.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - and
                  - or
                  description: The grouping operator that defines the relationship between filter nodes.
                children:
                  type: array
                  description: 'Contains the defined criteria.


                    **Note:** Additional conjunctions can be added as a separate children branch.'
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                        - and
                        - or
                        - criteria
                        description: 'Defines the function of each node.

                          - The grouping operator that defines the relationship between filter nodes.

                          - The value `critera` indicates that the node is a contact criteria.'
                      field:
                        type: string
                        description: The field name used as criterion.
                      operator:
                        type: string
                        description: The logical operator for comparing the specified field and its value.
                      value:
                        type: string
                        description: The value of the specified field.
              x-examples:
              - type: and
                children:
                - type: criteria
                  field: gender
                  operator: equals
                  value: female
                - type: criteria
                  field: age
                  operator: greater_or_equal
                  value: '22'
      tags:
      - Filter
    get:
      summary: Get Segment Contact Criteria
      description: 'Returns the contact criteria for the specified segment.


        For details on how the response body is structured, see [Create a segment](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NDY) endpoint.'
      operationId: getSegmentContactCriteria
      parameters:
      - name: segmentId
        in: path
        description: 'The segment identifier.


          **Note:** The identifier must not be *0*.'
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: object
                    description: The requested data.
                    properties:
                      type:
                        type: string
                        enum:
                        - and
                        - or
                        - criteria
                        description: 'Defines the function of each node.

                          - The grouping operator that defines the relationship between filter nodes.

                          - The value `critera` indicates that the node is a contact criteria.'
                      children:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - and
                              - or
                              - criteria
                              description: 'The grouping operator that defines the relationship between filter nodes.


                                The value `critera` indicates that the node is a contact criteria.'
                            field:
                              type: string
                              description: The field name used as criterion.
                            operator:
                              type: string
                              description: The logical operator for comparing the specified field and its value.
                            value:
                              type: string
                              description: The value of the specified field.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/{segmentId}/delete:
    get:
      summary: Delete a Segment
      operationId: deleteSegment
      parameters:
      - name: segmentId
        in: path
        description: The segment identifier.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/{segmentId}/contacts/count:
    get:
      summary: Count Contacts in a Segment
      description: 'Provides the number of contacts in the specified segment.


        **Note:** This endpoint does not return data immediately because it requires further processing.'
      operationId: countContactsInSegment
      parameters:
      - name: segmentId
        in: path
        description: The segment identifier.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: integer
                    description: The current number of contacts in the segment.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/{segmentId}/contacts/{contactId}:
    get:
      summary: Look Up a Contact in a Segment
      description: Looks up a specific contact in a segment. If the segment includes the contact, returns `true`, otherwise returns `false`.
      operationId: lookUpContactInSegment
      parameters:
      - name: segmentId
        in: path
        description: The segment identifier.
        required: true
        schema:
          type: integer
      - name: contactId
        in: path
        description: The contact identifier (`id`).
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See the example or [Response Codes](docs/response-codes/error-codes.md) for details.
                additionalProperties: false
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys [response code](docs/response-codes/error-codes.md).
                  replyText:
                    type: string
                    description: The summary of the [response](docs/response-codes/error-codes.md).
                  data:
                    type: boolean
                    description: Returns `true` if the contact is included in the specified segment. Otherwise returns `false`.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/{segmentId}/single_runs:
    post:
      summary: Run a Segment for a Single Contact
      description: 'Checks whether the specified contact is included in a segment and starts the segment running process.


        **Important:** Depending on the composition of the segment, the running time may take hours. Use the [Poll the status of a segment run for a single contact](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NTk) endpoint to check the status.'
      operationId: runContactSegmentSingle
      parameters:
      - name: segmentId
        in: path
        description: The identifier of the segment to run. Use the [List segments](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NDk) endpoint to get the identifier.
        required: true
        schema:
          type: string
      - name: contact_id
        in: query
        description: Checks whether the contact specified by its internal identifier is included in the segment. Use the [List Contact Data](reference/openapi.json/paths/~1v2~1contact~1query~1/get) or the [Get Internal Contact Identifiers](/reference/openapi.json/paths/~1v2~1contact~1query~1{keyId}={keyValue}/get) endpoint to get the internal identifier.
        schema:
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See [Response Codes](docs/response-codes/error-codes.md) for details.
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys response code. Successful requests return *0*.
                    default: 0
                  replyText:
                    type: string
                    description: Additional information on the status of the request.
                  data:
                    type: object
                    description: Contains the requested data, if applicable.
                    properties:
                      run_id:
                        type: string
                        description: The identifier of the segment run. Provide this identifier on the [Poll the status of a segment run for a single contact](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NTk) endpoint to check the status.
                      status:
                        type: string
                        enum:
                        - done
                        - error
                        - waiting
                        description: The status of the segment run process.
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/single_runs/{runId}:
    get:
      summary: Poll the Status of a Segment Run for a Single Contact
      description: "Poll this endpoint to check the status of a started segment run of a single contact. Once the process is completed, returns whether the specified contact is included in the segment.\n \n **Note:** Use the [Run a segment for a single contact](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NTg) endpoint to initiate the segment run and specify the contact."
      operationId: pollStatusContactSegmentSingle
      parameters:
      - name: runId
        in: path
        description: The identifier of the segment run. Get this identifier on the [Run a segment for a single contact](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NTg) endpoint to start the segment caclulation process.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See [Response Codes](docs/response-codes/error-codes.md) for details.
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys response code. Successful requests return *0*.
                    default: 0
                  replyText:
                    type: string
                    description: Additional information on the status of the request.
                  data:
                    type: object
                    description: Contains the requested data, if applicable.
                    properties:
                      status:
                        type: string
                        enum:
                        - done
                        - waiting
                        - error
                        description: The status of the segment run process.
                      result:
                        type: object
                        properties:
                          is_in_segment:
                            type: boolean
                            description: Returns whether the specified contact is included in the segment.
                      run_id:
                        type: string
                        description: The identifier of the segment run. Get this identifier on the [Run a segment for a single contact](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NTg) endpoint to start the segment caclulation process.
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/{segmentId}/runs:
    post:
      summary: Run a Segment for Multiple Contacts
      description: 'Starts the segment calculation process and returns information on the included contacts.


        **Important:** Depending on the composition of the segment, the running time may take hours. Use the [Poll the Status of a Segment Run for Multiple Contacts](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NjE) endpoint to check the status.'
      operationId: runContactSegmentBatch
      parameters:
      - name: segmentId
        in: path
        description: The identifier of the segment to run. Use the [List segments](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NDk) endpoint to get the identifier.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: See [Response Codes](docs/response-codes/error-codes.md) for details.
                properties:
                  replyCode:
                    type: integer
                    description: The Emarsys response code. Successful requests return *0*.
                    default: 0
                  replyText:
                    type: string
                    description: Additional information on the status of the request.
                  data:
                    type: object
                    description: Contains the requested data, if applicable.
                    properties:
                      run_id:
                        type: string
                        description: The identifier of the segment run. Provide this identifier on the [Poll the status of a segment run for a single contact](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NTk) endpoint to check the status.
                      status:
                        type: string
                        enum:
                        - done
                        - error
                        - waiting
                        description: The status of the segment run process.
        '404':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/default-response'
      security:
      - X-WSSE: []
      servers:
      - url: https://api.emarsys.net/api
      tags:
      - Filter
  /v2/filter/runs/{runId}:
    get:
      summary: Poll the Status of a Segment Run for Multiple Contacts
      description: "Poll this endpoint to check the status of a started segment run of multiple contacts. Once the process is completed, returns information on the contacts included in the segment.\n \n **Note:** Use the [Run a Se

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/openapi/emarsys-filter-api-openapi.yml