SAP Emarsys

SAP Emarsys Segments API

In this batch you may find endpoints related to segments. Published by SAP Emarsys as a Swagger 2.0 document with 11 operation(s). Part of the SAP Emarsys Core API. Authentication is the legacy X-WSSE UsernameToken header, which SAP Emarsys has deprecated with a final sunset at the end of 2026 in favour of OAuth 2.0 / OpenID Connect on the v3 surface. Errors are returned as a proprietary replyCode/replyText/data envelope and can appear inside HTTP 200 responses, so callers must inspect replyCode rather than the status code.

GitHub OpenAPI

Documentation

📖
Documentation
https://dev.emarsys.com/
📖
APIReference
https://dev.emarsys.com/docs/core-api-reference/ehr0tded4ctcw-emarsys-core-api-segments-endpoint-batch
📖
Authentication
https://dev.emarsys.com/docs/emarsys-core-api-guides/b3c3a1eba8515-authentication

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/openapi/emarsys-segments-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/emarsys/refs/heads/main/overlays/emarsys-segments-overlay.yaml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/emarsys-segments-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

emarsys-segments-openapi.yml Raw ↑ 
swagger: '2.0'
info:
  title: Emarsys Core API - Segments endpoint batch
  description: In this batch you may find endpoints related to segments.
  version: v2
host: api.emarsys.net
basePath: /api
schemes:
  - https
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
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - in: body
          name: body
          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'
      schemes:
        - https
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/filter/{segmentId}':
    get:
      summary: List Segments
      description: Generates a list of segments.
      operationId: listSegments
      produces:
        - application/json
      parameters:
        - name: segmentId
          in: path
          description: 'The identifier of the segment. If provided, returns the details of the specified only.'
          required: true
          type: string
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
      x-internal: false
  '/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
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - name: segmentId
          in: path
          description: |-
            The segment identifier.

            **Note:** The identifier must not be *0*.
          required: true
          type: integer
        - in: body
          name: body
          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'
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
    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
      produces:
        - application/json
      parameters:
        - name: segmentId
          in: path
          description: |-
            The segment identifier.

            **Note:** The identifier must not be *0*.
          required: true
          type: integer
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/v2/filter/{segmentId}/delete':
    get:
      summary: Delete a Segment
      operationId: deleteSegment
      produces:
        - application/json
      parameters:
        - name: segmentId
          in: path
          description: The segment identifier.
          required: true
          type: integer
      schemes:
        - https
      responses:
        '200':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
        '400':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/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
      produces:
        - application/json
      parameters:
        - name: segmentId
          in: path
          description: The segment identifier.
          required: true
          type: integer
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/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
      produces:
        - application/json
      parameters:
        - name: segmentId
          in: path
          description: The segment identifier.
          required: true
          type: integer
        - name: contactId
          in: path
          description: The contact identifier (`id`).
          required: true
          type: integer
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/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
      produces:
        - application/json
      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
          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.'
          type: number
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
        '404':
          description: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/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.
         
         **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
      produces:
        - application/json
      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
          type: string
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/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
      produces:
        - application/json
      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
          type: string
      schemes:
        - https
      responses:
        '200':
          description: ''
          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: ''
          schema:
            $ref: '#/definitions/default-response'
      security:
        - X-WSSE: []
  '/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.
         
         **Note:** Use the [Run a Segment for Multiple Contacts](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NjA-run-a-segment-for-multiple-contacts) endpoint to initiate the segment run.
         
         **Note:** The contact list created as a result of the segment run is available for at least 12 hours. You can find its ID in the response: `contact_list_id`.
      operationId: pollStatusContactSegmentBatch
      produces:
        - application/json
      parameters:
        - name: runId
          in: path
          description: 'The identifier of the segment run. Get this identifier on the [Run a Segment for Multiple Contacts](https://dev.emarsys.com/docs/emarsys-api/b3A6MjQ4OTk4NjE) endpoint to start the segment caclulation process.'
          required: true
          type: string
      schemes:
        - https
      responses:
        '200':
          description: ''
          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:
                      contact_list_id:
                        type: number
                        description: 'The identifier of the contact list. To see which contacts 

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